Improving user and developer guides for zstash#452
Conversation
|
PR generated with this prompt: Please update the documentation to be more comprehensive, to resolve #451. There should be two major sections: User Guide & Developer Guide. Each of those should have sub pages. You do not need to run any code or tests. You should only be editing the documentation. You should not try to render the docs yourself. The priority should be adding and moving content. You should be hesitant about removing any material, unless the documentation is clearly out-of-date or inconsistent with how the code is implemented. Some key things to include in the user guide:
Some key things to include in the developer guide:
|
|
@copilot It looks like you removed many files from the docs index, so that they still exist but are inaccessible. These pages (or content from them) should be moved into the User Guide or Developer Guide (unless of course the content is obviously no longer accurate). |
Addressed in 8f31422. The docs index now explicitly lists the user-guide and developer-guide subpages so the existing pages remain easy to find after the guide reorganization. |
There was a problem hiding this comment.
Pull request overview
This PR reorganizes and refreshes the Sphinx documentation for zstash by
splitting content into clearer User Guide and Developer Guide sections, adding
new Globus- and release-focused pages, and updating many examples/figures to use
explicit Sphinx directives.
Changes:
- Added a new User Guide structure (index + new pages for design, getting
started, Globus, support, and archived docs). - Added a new Developer Guide structure (testing, tar tracking modes, and
release process pages), replacing older release documentation. - Reformatted many command examples and figure references (e.g.,
code-block
directives and/ _static / figurespaths).
Reviewed changes
Copilot reviewed 21 out of 33 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/source/user_guide/usage.rst | Reformats usage examples and adds cross-links (currently contains broken Sphinx :doc: references and a few example inaccuracies). |
| docs/source/user_guide/support.rst | Adds a new support page (needs “GitHub” capitalization fix). |
| docs/source/user_guide/index.rst | Introduces User Guide toctree (currently points at directories instead of */index). |
| docs/source/user_guide/globus/intro.rst | Adds Globus introduction and workflow guidance. |
| docs/source/user_guide/globus/index.rst | Adds Globus section toctree. |
| docs/source/user_guide/globus/configuration.rst | Documents ~/.zstash.ini Globus configuration and related token files. |
| docs/source/user_guide/getting_started.rst | New user-guide “Getting started” (replaces the prior top-level page). |
| docs/source/user_guide/design.rst | New design considerations page (why zstash vs alternatives). |
| docs/source/user_guide/database.rst | Converts database examples to code-block formatting (includes a “tar fole” typo). |
| docs/source/user_guide/best_practices.rst | Reformats examples and updates figure paths into /_static/figures/. |
| docs/source/user_guide/archived_documentation/tutorial.rst | Adds an archived tutorial for older zstash versions. |
| docs/source/user_guide/archived_documentation/index.rst | Adds an “Archived Documentation” section index/toctree. |
| docs/source/index.rst | Reworks main landing page to describe User/Developer guide structure (contains :doc: links that should target */index). |
| docs/source/getting_started.rst | Removed old top-level “Getting started” page (content moved under user_guide/). |
| docs/source/dev_guide/testing.rst | Adds a consolidated testing guide page. |
| docs/source/dev_guide/tar_tracking_modes.rst | Adds documentation for tar lifecycle/transfer behavior across --hpss modes. |
| docs/source/dev_guide/releases/release_candidates.rst | Adds detailed release-candidate steps. |
| docs/source/dev_guide/releases/production_releases.rst | Adds detailed production release steps. |
| docs/source/dev_guide/releases/index.rst | Adds release section index/toctree. |
| docs/source/dev_guide/release.rst | Removes prior monolithic release guide (replaced by dev_guide/releases/*). |
| docs/source/dev_guide/release_testing.rst | Removes prior release testing doc (but dev_guide/index.rst still references it). |
| docs/source/dev_guide/project_standards.rst | Updates figure paths and modernizes examples to use code-block. |
| docs/source/dev_guide/index.rst | Updates Developer Guide toctree (currently references removed release_testing and should point to releases/index). |
| docs/source/dev_guide/contributing_to_docs.rst | Updates docs contribution guide and figure path. |
| docs/source/_static/figures/pre-commit-passing.png | Adds/updates a figure asset used in Developer Guide. |
| docs/source/_static/figures/pre-commit-flow.svg | Adds/updates a figure asset used in Developer Guide. |
| docs/source/_static/figures/git-flow.svg | Adds/updates a figure asset used in Developer Guide. |
| docs/source/_static/figures/docs-version-selector.png | Adds/updates a figure asset used in docs contribution guide. |
Comments suppressed due to low confidence (7)
docs/source/user_guide/usage.rst:45
- The :doc: targets here don’t exist:
user_guide/configurationis not present in the docs tree, anduser_guide/globusis a directory (its docname is typicallyuser_guide/globus/indexor a specific page likeintro). This will break Sphinx builds and cross-references.
docs/source/user_guide/usage.rst:147 - Same broken :doc: references as earlier:
user_guide/configurationdoesn’t exist, anduser_guide/globusshould point to a real document (e.g.,user_guide/globus/introoruser_guide/globus/index).
docs/source/user_guide/usage.rst:90 - These
hsicommands run inside the interactivehsiprompt, but the example is shown as plain bash commands (nohsi>/>prompt). That can mislead users into thinkingcd/lsrun in their shell afterhsiexits.
docs/source/user_guide/database.rst:79 - Typo in the section title: "tar fole" should be "tar file".
docs/source/user_guide/usage.rst:557 - The command is rendered as
zstash_lshere, but the CLI subcommand iszstash ls(with a space). As written, this looks like a non-existent command.
docs/source/user_guide/usage.rst:570 - Same issue as above:
zstash_lsis not a valid command name; it should bezstash ls.
docs/source/user_guide/usage.rst:568 - This example creates an archive named
different_hpss_archive(line 566) but then runszstash lsagainstdifferent_archivehere. That mismatch makes the example incorrect.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
cd docs
make html
cp -r _build/ /global/cfs/cdirs/e3sm/www/forsyth/zstash_docs_20260622
chmod -R 755 /global/cfs/cdirs/e3sm/www/forsyth/zstash_docs_20260622Latest docs rendered here |
|
Confirmed commit above fixes the usage docs link -- https://portal.nersc.gov/cfs/e3sm/forsyth/zstash_docs_20260622_try2/html/user_guide/getting_started.html |
|
Remaining action items:
|
Pull request created by AI Agent