Repository navigation
docs: reword property docstrings the API pages split at a colon - #221
Merged
Merged
Conversation
For a property, napoleon reads a first docstring line of the form "text: more text" as "type: description". Eight properties had one, so their pages and their rows in the class tables showed only the words after the colon, with the words before it as a "Type" field. `Project.name` read "the directory name." with "Type: The project's name" under it. Reworded without the colon: `Project.name`, `Grid.dims`, `ProjectConfig.transport`, `ProjectConfig.footprint`, `Simulation.transport`, `Variant.realization_numbers`, `FootprintAccessor.config` and `HysplitConfig.effective_maxpar`.
Codecov Report✅ All modified and coverable lines are covered by tests.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The API pages of eight properties showed half of their description as a type. This rewords those eight docstrings; no code changes.
What was wrong. For a property, an attribute or module data, napoleon reads a first docstring line of the form
text: more textastype: description, its inline form for those objects. Eight properties had a colon in that line, so each one's page, and its row in the class's table, showed only the words after the colon, with the words before it under "Type". Methods, functions and classes are not read this way.Before,
Project.name:"""The project's name: the directory name."""rendered as
After:
"""The project's name, which is the name of its directory."""renders as that one sentence, on the page and in the table of
Project.The eight (all of the ones a docs build shows):
Project.name,Grid.dims,ProjectConfig.transport,ProjectConfig.footprint,Simulation.transport,Variant.realization_numbers,FootprintAccessor.config, andHysplitConfig.effective_maxpar. Each is reworded without the colon, with a comma, a "which", parentheses, or a second sentence.CHANGELOG.mdhas a line under Fixed.How they were found. I built the docs from
mainand read every object in the 389 built pages for a "Type" field under its description: 8 of 67 properties had one, and no method, function, class, attribute or data did. A search of the source with napoleon's own rule gave the same eight properties. After the change the same build has none, and I read all eight pages and their table rows, before and after.Checked.
just lint,just type-check,just imports,just docstr,just test(1,285 passed, 1 skipped),just pre-commit(every hook, all files), and a cleanjust build-docswith warnings as errors.Not run: the integration and fidelity suites (no code changed; CI runs them).
Left alone. Eight
#:comments on module constants and instance attributes have the same form (Step,UNITS,FOOTPRINT_SCHEMA,FAILURE_SUFFIX,Output.directory,Met.directory,When,FOOTPRINT_COLUMNS). No page shows any of those comments today, so nothing renders wrongly, and there was nothing to check a rewording against. They would be split the same way if they got pages.