Skip to content

docs: fill missing guides and organize documentation - #274

Open
krowvin wants to merge 1 commit into
mainfrom
docs/audit-navigation
Open

krowvin wants to merge 1 commit into
mainfrom
docs/audit-navigation

Conversation

@krowvin

@krowvin krowvin commented Sep 24, 2026

Copy link
Copy Markdown
Collaborator

Changes

  • Add concise USGS, SHEF configuration, time-series loading, and troubleshooting guides to fill gaps found against the command tree.
  • Organize navigation by setup, transfers, management, reference, and development; preserve existing page URLs and add a workflow index.
  • Correct stale SHEF and user-role examples, document optional dependencies and PowerShell setup, and fix the README measurement import.
  • Register new command guides in ownership metadata and regenerate maintainer notes/CODEOWNERS.

Testing

  • Strict Sphinx HTML build (python -m sphinx -nW -E -b html docs docs/_build/html): passed.
  • Sphinx linkcheck: passed with the repository's existing ignore rules.
  • Local parser audit: 28 documented command snippets accepted without invoking callbacks; generated guide navigation and markup checked.
  • Ownership metadata unit tests: 2 passed; generator check and git diff --check passed.
  • Documentation-only change; no live CDA/USGS writes or transfer integration tests performed.

@krowvin
krowvin requested a review from Enovotny as a code owner September 24, 2026 01:12

@krowvin krowvin left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding some extra thoughts in. Thanks to @msweier for bringing up the docs need some love!

Comment thread docs/cli/setup.rst

See :doc:`Common API Arguments <api_arguments>` for environment setup examples.

Use :doc:`login` for browser authentication or configure an API key for your

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might want a note that the login command does not work on the T7. It can't launch the local browser for the redirect it seems.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having names on files is new. This means our names will also show up in SEO(?) While it is useful to know when a doc file is changed I'm not so sure we should take the step into publishing our names on the doc site.

Something in saying everyone is responsible for complete, legible, and updated docs.

@msweier thoughts?

Comment thread docs/cli/shef.rst

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Command or dependency not found
----------------------------------------

Run ``python -m pip show cwms-cli`` in the environment where you installed the

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this fit better in a dedicated block about virtual environments instead of assuming everyone will have a venv? Venv is still an advanced topic depending on the target audience.

@krowvin
krowvin requested a review from msweier September 24, 2026 13:59

This branch has not been deployed

No deployments
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