docs: starter pack

[IronCore864]

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:

• 1st commit is everything from the starterpack
• the remaining commits are necessary config and hacks to make it work.

See the preview here.

Open to discuss:

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.
2. Shall we remove the Makefile and come up with a short readme about pulling the latest starter pack templates and building docs locally? Pulling is simply cloning and copy-pasting, building is running some python scripts, pip install, then sphinx build. We benefit not much from the Makefile and it adds another thing in this repo.

[AnneCYH]

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.

[dimaqq]

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.

[benhoyt]

Yeah, I agree that we need to figure out a better way to run this than a Makefile which installs a bunch of stuff to the local machine. Perhaps we can just use a tox.ini that runs Sphinx.

I agree about removing all files we don't need (the cheat sheets).

[benhoyt]

Looks good to me. Just a couple of minor comments.

[dimaqq]

Most of my comments are about things to do in a separate PR.

Please find a place to note the remaining work somewhere.

[dimaqq]

I wonder what's the best way to handle the _static content.

My worry is that this many files and an occasional long file like this one pollute the repository. Maybe the owner can decide if that's acceptable.

Is there a change to pull these files in at build time, as I imagine same files are needed in each project?

Alternatively, we could host a tarball in the repo, and unpack it only when building the docs.

[dimaqq]

We'll need our stuff here... I wonder what's the best way to address this, make a jira sub-task or a github issue?

[tonyandrewmeyer]

When I try to build (with tox in the docs 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)

[IronCore864]

When I try to build (with tox in the docs 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.