feat: add basic sphinx docs #1711
Conversation
Uses a modified version of rockcraft's gen_cli_docs.py
There was a problem hiding this comment.
Mostly copied this from rockcraft
| runner = ignore_env_name_mismatch | ||
| source_dir = {tox_root}/{project_name} | ||
|
|
||
| [testenv:build-docs] |
There was a problem hiding this comment.
Looking at the CI for this PR, this reminds me of something I did in Snapcraft that I haven't upstreamed: https://github.com/canonical/snapcraft/blob/676e391446225901b5a09cfbfb4d11c186ce752d/.github/workflows/tox.yaml#L42
The problem is that if a command's docstring contains invalid RST text, it won't get caught by lint-docs in CI. The biggest offender in Snapcraft was single backticks instead of double backticks.
Think it's worthwhile to upstream to starbase?
There was a problem hiding this comment.
Probably worth it with a comment about why we're building them :-)
docs/reference/commands.rst
Outdated
There was a problem hiding this comment.
Building the docs is giving me a few warnings, one of which is extensions-commands.rst not being included here.
| :maxdepth: 2 | ||
|
|
||
| commands | ||
| models/index |
There was a problem hiding this comment.
This link 404's for me from the nav bar
lengau
force-pushed
the
work/CRAFT-2981/sphinx
branch
from
677f28a to
6f32246
Compare
Adds a Sphinx documentation project and some basic documentation. The purpose is to allow automatic generation of certain reference documentation that would otherwise need to be manually generated for juju.is.
This includes using the Starcraft standard
starbasesphinx docs, A command documentation generator from rockcraft, and additions to some pydantic models to copy documentation out of what's on juju.is.Fixes #1692