********
Sections
********

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


Pattern Used by WGA 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 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)


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.

- Heading 1:  above-and-below, for parts ######
- Heading 2:  above-and-below, for chapters  \*\*\*\*\*\*
- Heading 3:  ====== for sections
- Heading 4:  \-\-\-\-\-\- for subsections
- Heading 5:  ^^^^^^ for sub-subsections
- Heading 6:  """""" 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.

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



.. include:: external_links.txt