1.3. Parts, Chapters, Titles, Sections

Every Sphinx document has multiple level of headings. Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text.

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for this documentation, here is a suggested convention as covered in the Sphinx reStructuredText Primer to use them in this order:

  • # for title – with overline, for parts

  • * for subtitle – with overline, for chapters

  • =, for sections

  • -, for subsections

  • ^, for subsubsections

  • =, for paragraphs

They give structure to the document, which is used in navigation and in the display in all output formats. The part section header is not used at all. All regular documents starts with a title heading underlined by #. Therefore the specific names part, chapter, section,… might not match the actual context. Generally we speak about “sections” (or “section headings” or “section markers”).

Note

With reStructuredText, there is no leaving out a section level. If you write a chapter it is not possible to continue with a paragraph. Instead the next section must be of the type title.

If you try to do it overwise (chapter 1 * with overline → paragraph "), the “paragraph” is treated as a “title”. And if you continue by another chapter in the same file (chapter 2 * with overline → title #), sphinx-build got confused and at least produces a warning (Title level inconsistent) and possibly renders the result incorrectly.

the convention
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
####################################
Part -- Number Signs above and below
####################################

with overline, for parts

************************************
Chapter -- Asterisks above and below
************************************

with overline, for chapters

Title -- Number Signs
#####################

Suptitle -- Asterisks
*********************

Section -- Equal Signs
======================

Subsection -- Hyphens
---------------------

Subsubsection -- Circumflex
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Paragraph -- Double Quotes
""""""""""""""""""""""""""