How to add sections to documentation

Note

This page was written in the style of a How-to Guide according to The Diátaxis Framework.

This guide shows how to organize your documents in different parts: sections, subsections, and so on.

Pre-requisites

This guide assumes your project already has a working Sphinx documentation project in a folder called docs and the recommended folder structure. If you don’t have it, you can set it up with sphinx-quickstart following the tutorial Create a New Documentation Project.

Create sections, subsections and so on

You can organize your documents into:

• Sections.

• Subsections.

• Subsubsections.

• Paragraphs.

Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

Section name
============

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. Here, we follow the convention is used in Python Developer’s Guide for documenting with slight modification:

• # with overline, for page title

• = for sections

• - for subsections

• ^ for subsubsections

• " for paragraphs

Code:

##########
Title name
##########

Some text

Section name
============

Some text

Subsection name
---------------

Some text

Subsubsection name
^^^^^^^^^^^^^^^^^^

Some text

Paragraph name
""""""""""""""

Some text

Output:

Title name

Some text

Section name

Some text

Subsection name

Some text

Subsubsection name

Some text

Paragraph name

Some text