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 5 months 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.
Updated by Juliana Fajardini Reichow 4 months ago
Jason Ish wrote in #note-1:
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:
[...]
I'll start using these for new docs, and report back if I feel it's not working for whatever reason.
Thats also 6 levels, and HTML only has 6.
Personally I think I find myself using
~where they use @"@defkevI 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.
A brief google search didn't show me what I was looking for, will try again later.
Updated by Juliana Fajardini Reichow 4 months ago
This has the same suggestion (except for paragraphs, but I think it's a typo), but elaborates a bit more on how it's rendered and "hierarchy": https://lpn-doc-sphinx-primer.readthedocs.io/en/stable/concepts/heading.html
Updated by Juliana Fajardini Reichow 4 months ago ยท Edited
This will also involve understanding what is a part and what is a chapter, for us :P
this is important as, if we don't really have "parts", we end up losing a heading level.
AND agreeing if we'll really follow the Sphinx, or adapt anything.
And add a reference to these guidelines in our Docs guidelines.
Personally I think I find myself using ~ where they use @"@defkev
I, for no reason at all, tend to dislike ^ and prefer ~. Maybe because it's easier access on my keyboard.