.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
********
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:

.. code-block:: rst

    ****************
    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 :doc:`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:



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)



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



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).



Patterns Rejected for WGA Projects
**********************************
This pattern is suggested by `Sphinx's reST Primer <sphinx 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)