Skip to content

docs: copy-edit the package documentation for readability - #354

Draft
thodson-usgs wants to merge 1 commit into
DOI-USGS:mainfrom
thodson-usgs:docs/copy-edit
Draft

docs: copy-edit the package documentation for readability#354
thodson-usgs wants to merge 1 commit into
DOI-USGS:mainfrom
thodson-usgs:docs/copy-edit

Conversation

@thodson-usgs

Copy link
Copy Markdown
Collaborator

Stacked on #350. This branch sits on top of #350's commit, so the diff
shown here against main includes that PR's changes. The copy-edit itself is
the single commit c9e5b655, touching 40 files — reviewable on its own at
refactor/phase-2-transport-boundaries...docs/copy-edit.
Once #350 merges, the diff here collapses to just the copy-edit. Kept separate
so #350 stays one focused change.

A readability pass over the README, the Sphinx guides and architecture pages,
and the docstrings in every module. No behavior change.

What changed

The edits are small and local, applied consistently across ~40k words of
docstrings and ~1,750 lines of RST:

  • long sentences split (the worst were 45–75 words)
  • filler cut — "in order to", "please note", "it should be noted that", "simply"
  • passive constructions made active
  • vague pronouns given their referents
  • parameter descriptions re-led with what the value is, with constraints,
    defaults, and examples after it
  • summary lines collapsed to one imperative sentence on one line
  • list items made grammatically parallel
  • a recurring comma splice fixed: "If True, check SSL certificates, if False, do not check SSL, default is True""Whether to check SSL certificates. Default is True." (20 occurrences)

Net −88 lines. Nothing was restructured, reordered, or deleted.

Safety

  • Code is untouched. An AST comparison with docstrings masked shows every
    module's code byte-identical.
  • Examples are untouched. No line inside a .. doctest::, .. code-block::,
    or >>> example differs — verified by extracting all 287 example lines.
  • Full test suite passes, mypy --strict clean, Ruff lint and format clean.
  • A full Sphinx HTML build succeeds with no new warnings — no unresolved
    references, undefined labels, or heading-underline problems.

Repairs beyond copy-editing

These were found while reading and are genuine defects:

  • .. api: and .. timeconventions: were missing their leading underscore, so
    they were RST comments, not labels — any :ref: aimed at them resolved to
    nothing.
  • Three cross-references pointed at symbols that had moved or never existed:
    ChunkPlan.execute, ogc.engine._client_for (now in transport.pagination),
    and ChunkInterrupted under exceptions rather than ogc.interruptions.
  • A bullet in the architecture overview had unindented continuation lines, which
    docutils reported and which rendered wrongly.
  • Several numpydoc "Keyword Arguments" underlines were shorter than their titles.

Three places gained content — please check

Everything else is an edit of existing text. These add a claim:

  1. nldi.py had no module docstring. One was written; its statements about
    origins, return types, as_json, and the base URL were checked against the
    source.
  2. get_latest_daily's docstring was a copy of get_daily's and never said
    what made it "latest". Its summary now does, matching the latest-daily
    collection it queries and the wording its latest-continuous sibling already
    used.
  3. wqp.get_results now documents the ssl_check default that its eight
    sibling getters already documented.

Noticed, not changed — content decisions for a maintainer

  • get_continuous documents a maximum limit of 10000 while every other
    collection says 50000. Worth confirming upstream.
  • docs/source/userguide/dataportals.rst's portal table lists only NWIS, USGS
    Samples, StreamStats, WQP, and Water Services. It omits the Water Data OGC
    API, NGWMN, NLDI, and NWDC water use, all documented as first-class in the
    README, so the table reads as stale.
  • Several Parameters entries use name: rather than numpydoc's name : type,
    which likely parses wrong; name : type lines were out of scope for this pass.
  • get_time_series_metadata and get_combined_metadata each have parameters
    with a type line and no description.
  • errors.rst attributes chunking to "the server's ~8 KB URL limit"; project
    findings elsewhere describe the edge WAF as capping total request bytes
    (URL + body). Same number, possibly the wrong noun.

Findings in the deprecated nwis module were reviewed and intentionally left
alone.

A pass over the README, the Sphinx guides and architecture pages, and the
docstrings across every module. The edits are small and local: long
sentences split, filler cut ("in order to", "please note", "simply"),
passive constructions made active, vague pronouns given their referents,
parameter descriptions re-led with what the value is, and list items made
parallel. Nothing was restructured and no section was reordered.

Docstrings only: an AST comparison with docstrings masked shows the code
in every module unchanged, and no line inside a doctest, code block, or
``>>>`` example differs. The one exception is nldi.py, which had no module
docstring at all and now has one.

Two other additions worth naming. get_latest_daily's docstring was a copy
of get_daily's and never said what made it "latest"; its summary now does,
matching the latest-daily collection and the wording its latest-continuous
sibling already used. wqp.get_results now documents the ssl_check default
that its eight sibling getters already documented.

Repairs found along the way, beyond copy-editing:

* ``.. api:`` and ``.. timeconventions:`` were missing their leading
  underscore, making them RST comments rather than labels, so any ``:ref:``
  aimed at them resolved to nothing.
* Three cross-references pointed at symbols that had moved or never
  existed: ChunkPlan.execute, ogc.engine._client_for (now in
  transport.pagination), and ChunkInterrupted under exceptions rather than
  ogc.interruptions.
* A bullet in the architecture overview had unindented continuation lines,
  which docutils reported and which rendered wrongly.
* Several numpydoc "Keyword Arguments" underlines were shorter than their
  titles, and a few RST list continuations were mis-indented.

Verified: full suite passes, mypy --strict clean, Ruff lint and format
clean, and a full Sphinx HTML build succeeds with no new warnings.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015UVSiGgUyDRSbqNWM5HBbL
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