docs: improve syntax guides by asanvaq · Pull Request #19 · canonical/sphinx-stack-docs

asanvaq · 2026-07-03T13:22:56Z

Addresses #7

There is some confusion about the purpose of the currently included MD and rST "style guide" documents. This PR amalgamates them and converts them syntax reference documents, removing style guidelines.

Tabs and tables are used depending on the length of the reST or MyST syntax.

The image example was updated to include an image in the repository to shorten the syntax examples. This way, it all fits in a table.

I also included links to the intersphinx guide and updated the terminology of cross references to only use "labels", following Cross-references — Sphinx documentation.

AI disclosure: Claude Sonnet 4.6 was used to format tables and to initially combine both syntax guides. Content was checked, updated and arranged manually after that.

Have you updated CHANGELOG.md with relevant non-documentation file changes?
Have you updated the documentation for this change?

jahn-junior

Thanks for all of your work on this! I left a bunch of comments on things that jumped out at me, but I admit that I didn't scan through this line-by-line.

My biggest concern is that, while a single page is nice, we're now pushing the limit of what is maintainable by humans. Even the rendered page is a bit hard to parse with the onscreen elements and nesting. Maintenance aside, I think that users are more likely to be looking for syntax in one markup language or the other, which may outweigh the benefits of putting them side-by-side. I don't have a concrete request on this front, but I think it's something we should consider.

jahn-junior · 2026-08-11T22:03:46Z

@@ -0,0 +1,1520 @@
+---
+relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, https://github.com/canonical/lxd-sphinx-extensions, [reStructuredText&#32;Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical&#32;Documentation&#32;Style&#32;Guide](https://docs.ubuntu.com/styleguide/en)


Suggested change

relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, https://github.com/canonical/lxd-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en)

relatedlinks: https://github.com/canonical/canonical-sphinx, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en)

I assume the first link was meant to be the canonical-sphinx theme

canonical-sphinx-extensions was superseded by the standalone extension repositories.

jahn-junior · 2026-08-11T22:03:50Z

+# Syntax guide
+
+The Sphinx Stack supports [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) (reST), [Markdown](https://commonmark.org/) and
+[MyST](https://myst-parser.readthedocs.io/).


Suggested change

[MyST](https://myst-parser.readthedocs.io/).

The Sphinx Stack supports [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) (reST) and [MyST Markdown](https://myst-parser.readthedocs.io/).

MyST is a superset of Commonmark, so we probably don't need to explicitly mention Commonmark support.

jahn-junior · 2026-08-11T22:03:52Z

+
+* - Description
+  - <span style="text-transform: none">reST</span>
+  - <span style="text-transform: none">MyST</span>


Suggested change

- <span style="text-transform: none">MyST</span>

- reST

- MyST

jahn-junior · 2026-08-11T22:03:56Z

+`````{tab-item} reST
+To start a code block, either end the introductory paragraph with two colons (``::``)
+and indent the following code block, or explicitly start a code block with ``..
+code::``. In both cases, the code block must be surrounded by empty lines.


I understand this is meant to be less opinionated when it comes to style, but I think we should still promote a consistent use of reST and MyST syntax where possible.

For instance, I don't think we should bring extra attention to the :: code block syntax, as it isn't declarative and is even less visually accessible than the rest of reST syntax.

jahn-junior · 2026-08-11T22:03:58Z

+Or use the explicit directive:
+
+````
+.. code::


Since we're assuming that the project is based on the Sphinx Stack, can we advise users to use the code-block directive instead? It has a much more robust set of options. The code directive is the more barebones version provided by Docutils.

jahn-junior · 2026-08-11T22:04:51Z

+
+* - Output
+  - <span style="text-transform: none">reST</span>
+  - <span style="text-transform: none">MyST</span>


Suggested change

- <span style="text-transform: none">MyST</span>

- reST

- MyST

I won't duplicate this suggestion, but it's in all of these tables.

jahn-junior · 2026-08-11T22:04:54Z

+* - Output
+  - <span style="text-transform: none">reST</span>
+  - <span style="text-transform: none">MyST</span>
+* - <ol><li>Step 1<ul><li>Item 1<ul><li>Sub-item</li></ul></li><li>Item 2</li></ul></li><li>Step 2<ol><li>Sub-step 1</li><li>Sub-step 2</li></ol></li></ol>


Looks like another translation error? There are a few other instances of stuff like this the subsequent tables as well.

jahn-junior · 2026-08-11T22:04:59Z

+## Notes
+
+```{list-table}
+:header-rows: 1


I think we should bring attention to the standard admonition's args and options, as it's the one that should probably be used most often.

.. admonition:: <title> :class: <class>

jahn-junior · 2026-08-11T22:05:01Z

+
+`````{tab-item} reST
+**Globally**, in a file named ``reuse/substitutions.txt`` that is included in a
+custom ``rst_epilog`` directive (see the [rst_epilog documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog)):


We've removed this from the Sphinx Stack as well.

jahn-junior · 2026-08-11T22:05:04Z

+Please note:
+
+- Substitutions do not work on GitHub. Therefore, use substitution names that indicate
+  the included content (for example, `note_not_supported` instead of `reuse_note`).


Suggested change

Please note:

- Substitutions do not work on GitHub. Therefore, use substitution names that indicate

the included content (for example, `note_not_supported` instead of `reuse_note`).

Substitutions do not work on GitHub. Therefore, use substitution names that indicate the included content (for example, `note_not_supported` instead of `reuse_note`).

asanvaq added 8 commits July 3, 2026 15:20

docs: update to include reference to intersphinx how to

aa31786

docs: combine both syntax guides in one page

61e99fe

docs: improve wording and arrangement of syntax guide

64b7522

docs: remove rst and myst syntax pages

b3b39b6

docs: fix linking errors

1cd7f29

docs: add redirects

8169b89

docs: fix typo in redirects

59a2694

docs: updated terminology for linking to label

4b8cace

asanvaq marked this pull request as ready for review July 27, 2026 12:53

asanvaq requested review from SecondSkoll, a-velasco, dwilding, jahn-junior, medubelko and rkratky as code owners July 27, 2026 12:53

jahn-junior requested changes Aug 11, 2026

View reviewed changes

Navigation Menu

docs: improve syntax guides - #19

docs: improve syntax guides#19
asanvaq wants to merge 8 commits into
canonical:mainfrom
asanvaq:main

asanvaq commented Jul 3, 2026 •

edited

Loading

Uh oh!

jahn-junior left a comment •

edited

Loading

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

jahn-junior Aug 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -0,0 +1,1520 @@
		---
		relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, https://github.com/canonical/lxd-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en)

	[MyST](https://myst-parser.readthedocs.io/).
	The Sphinx Stack supports [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) (reST) and [MyST Markdown](https://myst-parser.readthedocs.io/).

	- <span style="text-transform: none">MyST</span>
	- reST
	- MyST

Conversation

asanvaq commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jahn-junior left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

asanvaq commented Jul 3, 2026 •

edited

Loading

jahn-junior left a comment •

edited

Loading