Documentation #7396
openuserguide: standardize rst formatting for chapters
Description
Ensure that throughout our documentation, we use the same markdown conventions for
- Chapters
- Sections
- Subsections
I think this may make help with building the docs (in terms of the references built),
but also adding new sections, as there could potentially be less conflicts nor fidgeting
when trying to add those ("what to use?" "Will this create a 'subsection' or a 'supersection'?")
Some possibly useful references:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
https://lpn-doc-sphinx-primer.readthedocs.io/en/stable/concepts/heading.html
Updated by Jason Ish 4 days ago
I'd recommend the one from sphinx-doc. Docutils is a little too generic and I don't actually see an order suggestion. lpn-doc duplicates the '='!
So that would be:
# with overline, for parts * with overline, for chapters = for sections - for subsections ^ for subsubsections " for paragraphs
Thats also 6 levels, and HTML only has 6.
Personally I think I find myself using ~ where they use @"@defkev
I also wonder if we could get sphinx to warn if there are more than 6 levels, as the HTML isn't likely to render how the author might think it will.