Cheat sheet

[ru-fu]

Add a documentation cheat sheet (and enable a few extensions that are documented in there).

Find it here: https://canonical-starter-pack--8.com.readthedocs.build/doc-cheat-sheet/

[ru-fu]

Thanks for the comments! Updated. :)

[ru-fu]

Do we want the cheat sheet in the navigation, or should it be an orphan (as it is now) for reference only?

[s-makin]

Do we want the cheat sheet in the navigation, or should it be an orphan (as it is now) for reference only?

Good question. If we put it in the navigation it's easier to find, but if we leave it as an orphan it doesn't muddy the Diataxis default framework.

Perhaps a link via the readme?

[pmatulis]

It would be great if we could align with the Charmed OpenStack product, which has been using RST for the last many years. This is its formatting guide.

[pmatulis]

I don't think we should aim at a cheat sheet. We can be more ambitious and make this part of a style guide, similar to what has been done with the Charmed OpenStack product.

[ru-fu]

I don't think we should aim at a cheat sheet. We can be more ambitious and make this part of a style guide, similar to what has been done with the Charmed OpenStack product.

I like that idea! But then this is the wrong place for it imo, and we should move the style guide to https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/ And to make things easier for authors, we could shorten the cheat sheet here down to really just a cheat sheet that gives the correct syntax but no explanation (and links to the full style guide).

What do you think?

[pmatulis]

We should definitely place company-wide resources in a company-managed repository (under the canonical org).

The guide you mentioned is https://github.com/evildmp/sphinx-rtd, which is in a personal namespace.

To be honest, I don't understand the purpose of this current starter-pack repository, which is under the company org.

Recommendation: keep one repository in the canonical org and given it an appropriate name, like

• sphinx-resources
• rtd-resources
• doc-resources

[ru-fu]

We should definitely place company-wide resources in a company-managed repository (under the canonical org).

The guide you mentioned is https://github.com/evildmp/sphinx-rtd, which is in a personal namespace.

To be honest, I don't understand the purpose of this current starter-pack repository, which is under the company org.

The purpose of this starter-pack repo is to provide an easy way for others to start with Sphinx documentation. The idea is that they can simply copy the contents of this repo into a doc folder of their project repo and start building docs, without having to configure anything (except for a few settings in conf.py, as documented). Ideally, this whole setup should be moved to an installable package in the future, but we're not there yet.

The other repo provides information on how to work with the starter pack and how to set up Read-the-Docs correctly. We need this information somewhere, and I don't think it should be in the same repo as the starter-pack, because then this information would be included in every doc set that uses the starter pack - and we don't want that. So I feel we need it in a separate repo (and the style guide should go into that repo). I agree though that it should be under the Canonical organization.

@evildmp Any thoughts?

[ru-fu]

I moved the style guide to https://github.com/canonical/sphinx-docs-guide/pull/6 now. I'll open a new PR for an actual cheat sheet. :)