Suricata

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.

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.

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

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.