Skip to content

docs: reword property docstrings the API pages split at a colon - #221

Merged
jmineau merged 1 commit into
mainfrom
docs/property-docstring-colons
Oct 11, 2026
Merged

jmineau merged 1 commit into
mainfrom
docs/property-docstring-colons

Conversation

@jmineau

@jmineau jmineau commented Oct 11, 2026

Copy link
Copy Markdown
Owner

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 text as type: 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

the directory name.

Type: The project's name

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, and HysplitConfig.effective_maxpar. Each is reworded without the colon, with a comma, a "which", parentheses, or a second sentence. CHANGELOG.md has a line under Fixed.

How they were found. I built the docs from main and 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 clean just build-docs with 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.

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

codecov Bot commented Oct 11, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

Files with missing lines Coverage Δ
src/stilt/config.py 96.15% <ø> (ø)
src/stilt/footprint/accessor.py 95.83% <ø> (ø)
src/stilt/project.py 97.52% <ø> (ø)
src/stilt/simulation.py 98.31% <ø> (ø)
src/stilt/spatial.py 93.10% <ø> (ø)
src/stilt/transport/hysplit/config.py 98.64% <ø> (ø)

@jmineau
jmineau merged commit 509c5eb into main Oct 11, 2026
14 checks passed
@jmineau
jmineau deleted the docs/property-docstring-colons branch October 11, 2026 07:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant