`attention` is missing in the notes section of the cheatsheet

[jugmac00]

In https://github.com/canonical/sphinx-docs-starter-pack/blob/main/doc-cheat-sheet.rst#notes you could add something like this

.. attention::
   This is a historical document. It might be out of date.

[ru-fu]

Yes, there's more admonitions in RST, but we don't recommend using them - see https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#notes That doesn't mean you're not allowed to use them if you see a clear need (but important should really get the same meaning across here ;) ), but they shouldn't go into the cheat sheet imo.

[jugmac00]

Thanks, @ru-fu, that makes a lot of sense. I must have missed that there is a special page for that.

Now that I know that, I think it is a bit confusing that there is both

• https://github.com/canonical/sphinx-docs-starter-pack/blob/main/doc-cheat-sheet.rst and
• https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/

Would it make sense to remove https://github.com/canonical/sphinx-docs-starter-pack/blob/main/doc-cheat-sheet.rst? and update the description in this repository's README that https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/ is not only a getting started type documentation, but that it contains all the necessary rst syntax?

[ru-fu]

No, the two serve different purposes.

The style guide has detailed explanation and is intended to be read in a rendered format. The cheat sheet is basically just a text file from which you can copy the markup you need if you can't remember the syntax. This is difficult to do from the style guide, since the markup is mostly part of tables there, which makes it easier to see and understand, but hard to copy because of wrong indentation. The cheat sheet doesn't have any detailed usage information, it's really just a list of what you can do. This is also stated at the top of the file. ;)

And this is also why the style guide is in a separate repo (since it doesn't make sense for every project that uses the starter pack to include it), while the cheat sheet is included here, since you want to open the file locally for copying.