Closed IronCore864 closed 4 months ago
Hi @IronCore864 ,
For your 2 open items.
The cheat sheets can be removed since we usually refer users to the main Style guides. However index.rst is needed for the documentation landing page.
I would advise against doing this. We use the starter pack for consistency across Canonical documentation sets. While the Makefile does indeed consist of a set of scripts/commands etc, we want to achieve a consistent user experience by running the same make run
command.
Hope that makes sense.
Thanks.
Hi @IronCore864 ,
For your 2 open items.
1 Shall we remove unnecessary files from the starter pack, or leave them as they are? Examples: doc-cheat-sheet-myst.md, doc-cheat-sheet.rst, index.rst, etc.
The cheat sheets can be removed since we usually refer users to the main Style guides. However index.rst is needed for the documentation landing page.
2 Shall we remove the Makefile and come up with a short readme about pulling the latest starter pack templates and building docs locally?
I would advise against doing this. We use the starter pack for consistency across Canonical documentation sets. While the Makefile does indeed consist of a set of scripts/commands etc, we want to achieve a consistent user experience by running the same
make run
command.Hope that makes sense.
Thanks.
My 2c: I'd rather not see a Makefile in a Python repo that uses Python tools like Sphinx. It's just a bit alien in the Python ecosystem.
Instead we've got entrypoints in pyproject.toml
or even shell incantations documents in a readme file.
I imagine that folks who maintain goland and c++ repos would have a similar, their-language-specific preference.
That being said, having a Makefile in the template repo is as a form of documenting the commands to run and a quick start that's meant to be adapted or translated to native tooling later on makes perfect sense.
When I try to build (with
tox
in thedocs
directory) I get:docs: commands[0]> sphinx-build -W --keep-going . _build/html Traceback (most recent call last): File "/home/tameyer/scratch/tiexenpebble/.tox/docs/bin/sphinx-build", line 5, in <module> from sphinx.cmd.build import main File "/home/tameyer/scratch/tiexenpebble/.tox/docs/lib/python3.12/site-packages/sphinx/cmd/build.py", line 17, in <module> from docutils.utils import SystemMessage ModuleNotFoundError: No module named 'docutils' docs: exit 1 (0.04 seconds) /home/tameyer/scratch/tiexenpebble/docs> sphinx-build -W --keep-going . _build/html pid=2850477 docs: FAIL code 1 (0.07=setup[0.02]+cmd[0.01,0.04] seconds) evaluation failed :( (0.11 seconds)
Fixed in the latest commits. Also .tox
is moved inside docs/
. Please take a final look.
Introducing Canonical starter pack into pebble docs.
Docs themselves are not updated yet, only starter pack templates and necessary hacks to make it work.
Commits explained:
See the preview here.
Open to discuss:
doc-cheat-sheet-myst.md
,doc-cheat-sheet.rst
,index.rst
, etc.