docs: use folders for each axis#456
Conversation
There was a problem hiding this comment.
Pull request overview
Reorganizes the Sphinx documentation into axis-based folders (Tutorials/Reference/Explanation) with new index.rst entrypoints and updates navigation/redirects to align Craft CLI’s docs structure with related projects ahead of the planned Starbase update.
Changes:
- Introduces axis folder
index.rstfiles and updates the main docs landing page to point at them. - Splits the previous “Explanations” monolithic page into multiple topic pages under
docs/explanation/. - Adjusts Sphinx apidoc generation output to write reference docs under
docs/reference/, and adds redirects for moved top-level pages.
Reviewed changes
Copilot reviewed 12 out of 13 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/tutorials/run-a-command-application.rst | Removes the per-page “Tutorials” header and adds a stable page anchor. |
| docs/tutorials/index.rst | Adds Tutorials section index and toctree. |
| docs/reference/index.rst | Adds Reference section index and toctree entry for generated API docs. |
| docs/redirects.txt | Adds redirects for moved top-level docs pages. |
| docs/index.rst | Updates site navigation/toctrees and landing-page cards to point to new index pages. |
| docs/explanation/presenting-messages.rst | Converts to a single-topic Explanation page with a new anchor. |
| docs/explanation/log-management.rst | Adds new Explanation topic page for log management (and preserves legacy ref label). |
| docs/explanation/index.rst | Adds Explanations section index and toctree for the split topic pages. |
| docs/explanation/hidden-common-commands.rst | Adds new Explanation topic page for hidden/common commands. |
| docs/explanation/global-args.rst | Adds new Explanation topic page for global args (and preserves legacy ref label). |
| docs/explanation/emit-mode.rst | Adds new Explanation topic page for emit mode. |
| docs/explanation/command-groups.rst | Adds new Explanation topic page for command groups, including a reference link to API docs. |
| docs/conf.py | Updates apidoc output directory to docs/reference/ and changes apidoc exclusions; configures redirects file. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| module = os.path.join(cur_dir, "..", "craft_cli") | ||
| exclude_patterns = ["*pytest_plugin*"] | ||
| main(["-e", "--no-toc", "--force", "-o", cur_dir, module, *exclude_patterns]) | ||
| exclude_patterns = ["*pytest_plugin*", "*dispatcher*"] |
There was a problem hiding this comment.
Everything in craft_cli.dispatcher was re-exported in the top-level craft_cli module. This meant that for the purposes of autogen docs from apidoc, CommandGroup could resolve to either craft_cli.CommandGroup or craft_cli.dispatcher.CommandGroup, and the ambiguity was raised as an error.
Since everything is re-exported, this just excludes that module from the autogen docs. This isn't a very elegant approach, but these autogen docs need a closer look than what is reasonable to do in this PR so this is the quick and dirty solution.
| "github_url": "https://github.com/canonical/craft-cli", | ||
| } | ||
|
|
||
| linkcheck_ignore = ["craft_cli.dispatcher.html#craft_cli.dispatcher.CommandGroup"] |
There was a problem hiding this comment.
This ignore was solving a similar issue caused by the same root problem, and was no longer needed now that it isn't being generated anymore.
There was a problem hiding this comment.
These were verbatim migrations, I only took the time to fix links.
Signed-off-by: Michael DuBelko <michael.dubelko@gmail.com>
make lint && make test?This is done in preparation for a Starbase update. I didn't make any attempt to improve content or fix anti-patterns within any of the files, I only aimed to get Craft CLI aligned with the structure of other projects.
index.rstfiles and each topic moved into its own file