6. Sections

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

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

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

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