Update header levels to be consistent

[deoren]

While working on some module docs recently I noted that the header level syntax was inconsistent between at least two of them. If two, then likely more.

Task list

• [ ] Define section headers (style guide?)
• [ ] Create template for new pages (perhaps a template per page type?)

Guides for section headers

1. http://www.sphinx-doc.org/en/stable/config.html#confval-text_sectionchars
2. http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections
3. https://devguide.python.org/documenting/#sections
4. http://docs.ckan.org/en/latest/contributing/documentation.html#section-titles

Notes

The docutils page confirms what characters are valid for forming section headers:

The following are all valid section title adornment characters:

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ Some characters are more suitable than others. The following are recommended:

= - ` : . ' " ~ ^ _ * + #

The Python guide (link 3) is a little more specific with their suggested convention:

# with overline, for parts * with overline, for chapters =, for sections -, for subsections ^, for subsubsections ", for paragraphs

The text_sectionchars option on the Sphinx doc page is intended for text output:

A string of 7 characters that should be used for underlining sections. The first character is used for first-level headings, the second for second-level headings and so on.

The default:

'*=-~"+`'.

The CKAN documentation (link 4) provides this recommendation:

===============
Top-level title
===============

------------------
Second-level title
------------------

Third-level title
=================

Fourth-level title
------------------

I'm partial to the CKAN recommendation myself as it is simple enough: the - character visually appears to be a smaller version of =, which suggests that it is a subsection of it.

[deoren]

After giving this some more thought, I think it may be worth sticking with the established style that the Sphinx project uses for their own documentation. I'm not a fan of the characters chosen for the levels, but if we can simply reference an existing style used by multiple large projects (which is already in their docs as a suggested approach), it should make it easier to work with new contributors (existing reference material to point them to).

[rgerhards]

Actually, I admit that the style currently used in rsyslog is not consistent. I myself would appreciate if we had a simple README or CONTRIB (or whatever) document that spells out how the rsyslog-doc project uses it. TBH, I do not really care what it is, as long as I know where I can find what to use. Of course, it does help if we follow some established and well-known policy ;-) Just my personal 2cts (NOT speaking as rsyslog maintainer here!).

[deoren]

@rgerhards: I myself would appreciate if we had a simple README or CONTRIB (or whatever) document that spells out how the rsyslog-doc project uses it.

Me too, actually. I don't necessarily recall what to use where (mainly because I wasn't sure yet what it would end up being), so having it documented is the way to go. I'll work on this soon now that the light bulb has switched on for me.

@rgerhards: TBH, I do not really care what it is, as long as I know where I can find what to use.

I think I've come to the same conclusion. Consistency and clear direction is more important than the characters used for the headers.

@rgerhards: Of course, it does help if we follow some established and well-known policy

I completely agree. I have this on my wall: https://xkcd.com/927/

@rgerhards: Just my personal 2cts (NOT speaking as rsyslog maintainer here!).

Thanks for sharing your thoughts and thanks also for emphasizing that you're not making an executive call. I think I would parse out when you're doing that vs offering feedback, but it's always nice to know for sure.