4. Sections

Sections are created in a reST file by simply underlining the section title with a punctuation character. The Docutils reST parser figures out what “level” you mean by the pattern used in each file. Consistency of underlining across a set of files (e.g. when using Sphinx to build a document set) is not required, but is recommended for sake of improved readability and maintainability. Example:

****************
Example Headings
****************

Text that introduces this page.

Heading Level 2
***************

Text under heading level 2.

Heading Level 3
===============

Text under heading level 3.

Heading Level 4
---------------

Text under heading level 4.

Heading Level 5
~~~~~~~~~~~~~~~

Text under heading level 5.

Heading Level 6
^^^^^^^^^^^^^^^

Text under heading level 6.

Heading Level 7
'''''''''''''''

Text under heading level 7.

Below level 6, the Docutils parser's HTML output generator compensates for the
lack of an ``<h7>`` HTML tag by adding an "aria-level" attribute to the ``<h6>``
tag like this:

.. code-block:: html

    <h6 aria-level="7"> . . . </h6>
    <h6 aria-level="8"> . . . </h6>
    <h6 aria-level="9"> . . . </h6>

and so on for levels beyond.  This is a clever strategy used by Docutils that
both removes the 6-level limitation as well as enabling authors to target those
types of headings using special CSS selectors.  Example:

.. code-block:: css

    h6[aria-level="7"] { font-size: small;                                    }
    h6[aria-level="8"] { font-size: small; text-decoration: underline;        }
    h6[aria-level="9"] { font-size: small; text-decoration: underline dotted; }
    /* etc. */

While this is not very useful, it is illustrative and so is included to plant
idea seeds to help you think about what you might want to do with it.

Heading Level 8
"""""""""""""""

Text under heading level 8.

Heading Level 9
:::::::::::::::

Text under heading level 9.

See Example Headings to see how this looks in a real output page.

The choice of underlining characters can be mixed and matched, but must remain consistent throughout each document (page). In a multi-document (page) project using Sphinx, consistency between documents (pages) also helps Sphinx properly format tables of contents and navigation trees.

Use of the “above-and-below” decoration is optional, and more than 6 levels are supported by Docutils, but may be limited by the chosen output format.

Because of this “loose” requirement, many “standards” have arisen in different documentation environments. Here are a few:

4.1. Pattern Used by WGA Doc/Authoring Projects

This pattern was chosen ultimately because it offers consistency with WGA C-language projects and is thus easy to remember: the first 4 tiers correspond to the pattern already in use (and documented) for C-code documentation:

  • Heading 1: above-and-below ****** (top of each .rst file)

  • Heading 2: below only ****** (3 lines of whitespace above)

  • Heading 3: ====== (2 lines of whitespace above)

  • Heading 4: ------ (hyphens) (at least 1 line of whitespace above)

  • Heading 5: ~~~~~~ (at least 1 line of whitespace above)

  • Heading 6: ^^^^^^ (at least 1 line of whitespace above)

4.2. Pattern Used by LVGL Documentation

  • Heading 1: above-and-below ======

  • Heading 2: ****** for sections

  • Heading 3: ------ for subsections

  • Heading 4: ~~~~~~ for sub-subsections

  • Heading 5: ^^^^^^ for sub-sub-subsections

  • Heading 6: '''''' (single quotes) for sub-sub-sub-subsections

4.3. How Typora Exports to reStructuredText

  • Heading 1: below only ====== (i.e. not above-and-below)

  • Heading 2: ------ (hyphens)

  • Heading 3: ~~~~~~

  • Heading 4: ^^^^^^

  • Heading 5: '''''' (single quotes)

  • Heading 6: not supported (output as spaces [0x20], so likely a bug in Typora).

4.4. Patterns Rejected for WGA Projects

This pattern is suggested by Sphinx’s reST Primer.

  • Heading 1: above-and-below, for parts ######

  • Heading 2: above-and-below, for chapters ******

  • Heading 3: ====== for sections

  • Heading 4: ------ (hyphens) for subsections

  • Heading 5: ^^^^^^ for sub-subsections

  • Heading 6: """""" (double quotes) for sub-sub-subsections

We were thinking about using the pattern below, combining already-in-use Perl and C comment block hierarchy, but have since declined using it since it would represent needless additional conversion work on existing documents. It does, however, make visual sense since each character has its own apparency of “height” and “boldness”, and the progression of each gets smaller as the heading levels progress downward.

  • Heading 1: above-and-below ######

  • Heading 2: ######

  • Heading 3: ******

  • Heading 4: ======

  • Heading 5: ------

  • Heading 6: ~~~~~~

Another pattern considered based on its matching the first 5 tiers of Typora-exported reStructuredText. But there are not very many .md files that need to be converted so use of this pattern was declined.

  • Heading 1: below only ======

  • Heading 2: ------ (hyphens)

  • Heading 3: ~~~~~~

  • Heading 4: ^^^^^^

  • Heading 5: '''''' (single quotes)

  • Heading 6: """""" (double quotes)