Project

General

Custom queries

Profile

Actions

Documentation #7396

open

userguide: standardize rst formatting for chapters

Added by Juliana Fajardini Reichow 6 months ago. Updated 5 days ago.

Status:
New
Priority:
Low
Assignee:
Target version:
Affected Versions:
Effort:
Difficulty:
Label:

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

Actions #1

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.

Actions #2

Updated by Juliana Fajardini Reichow 5 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 @"@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.

A brief google search didn't show me what I was looking for, will try again later.

Actions #3

Updated by Juliana Fajardini Reichow 5 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

Actions #4

Updated by Juliana Fajardini Reichow 5 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.

Actions #5

Updated by Jason Ish 5 days ago

I couldn't find any special meaning behind the order, and using overlines. The PDF appears to be based purely on hierarchy. So I think we should define 6 (per HTML) and each individual documentation page starts with the first one. Perhaps:

- #
- *
- =
-
~
- ^

But open to suggestions?

Actions #6

Updated by Juliana Fajardini Reichow 5 days ago

Jason Ish wrote in #note-5:

I couldn't find any special meaning behind the order, and using overlines. The PDF appears to be based purely on hierarchy. So I think we should define 6 (per HTML) and each individual documentation page starts with the first one. Perhaps:

- #
- *
- =
- -
- ~
- ^

But open to suggestions?

to me, this works. As I mentioned in another chat, I think the most important thing is agreeing to our standard, registering this in our docs, and starting to enforce and stardardize.

Actions

Also available in: Atom PDF