LaTeX Document Structure in Sphinx Projects

2025-12-12

Sphinx can generate documentation in several formats, but the Sphinx documentation tends to focus on HTML output. Here, I provide an overview of the structure of LaTeX documents generated by Sphinx.

Example Project

My discussion below draws on an example project with the requisite Sphinx configuration file (conf.py), as well as a root document (index.rst), and an “about” page (about.rst).

The configuration file, among other settings, contains:

project = "StructExample"
author = "A. Writer"
release = "1.0.0"

The root document contains headings and a toctree directive that links to the about page:

Heading A
=========

Heading B
---------

.. toctree::
   :caption: TOC Caption

   about

The about page also contains two headings:

Heading C
=========

Heading D
---------

LaTeX Document Classes

Sphinx supports two LaTeX document classes, report and article, which correspond to two Sphinx themes: “manual” and “how-to guide.” By default, Sphinx creates “manuals” (LaTeX report documents). You can set the latex_theme option in conf.py to "howto" to generate a LaTeX article.

Generate LaTeX Documents

You can use the Makefile created by sphinx-quickstart to generate LaTeX documents (make latex), or to generate LaTeX and PDF documents at the same time (make latexpdf).

Titles

Sphinx treats titles for HTML and LaTeX documentation differently. To clarify the specifics of LaTeX documentation, I will discuss the more well-documented HTML output first.

HTML Titles

By default, Sphinx creates a <title> element in the HTML header based on three pieces of information:

The string assigned to the project option in conf.py
The release number assigned to the release option in conf.py
The first, top-level heading that appears in the root document (by default, index.rst)

In the example project above, Sphinx creates the following in the HTML header:

<title>Heading A -- StructExample 1.0.0 documentation</title>

The <title> element does not appear on the HTML page rendered by the web browser; instead, different Sphinx templates use the title components in different ways. The default alabaster theme creates an <h1> element with the project name (“StructExample”) on every HTML page, whereas the classic theme creates a <div> element with the project name and release number (“StructExample 1.0.0 documentation”). Both the alabaster and classic themes also create <h1> elements for all top-level headings on each page. In the example project, this means that “Heading A” appears as an <h1> element in index.html and “Heading C” appears as an <h1> element in about.html.

LaTeX Titles

By default, Sphinx uses the project name in conf.py as the LaTeX document title in the preamble. Sphinx also uses a custom command for the release number. In the case of the example project above:

\title{StructExample}
\release{1.0.0}

In the PDF document generated from the LaTeX document, the release number appears beneath the title, as “Release 1.0.0”.

You can also use the latex_documents option in conf.py to specify a document title. For example:

latex_documents = [
    (
        "index.rst",  # Root document
        "StructExample.tex",  # Name of LaTeX file
        "Alternative Title for StructExample",  # LaTeX document title
        "Another Author",  # LaTeX document author
        "manual",  # LaTeX theme
        False,  # toctree_only option
    )
]

Sphinx then generates a LaTeX document with a preamble that contains:

\title{Alternative Title for StructExample}

Note that the default LaTeX title discussed above does not contain “Heading A.” In contrast to HTML documentation, Sphinx ignores the top-level heading (“Heading A”) in the root document when creating LaTeX documentation, but only if there is only one such top-level heading. The heading at the next level (“e.g. Heading B”) is then used as the first chapter title (in a Sphinx manual / LaTeX report) or section name (how-to guide / article). (More on this in a moment.)

If, however, there are multiple top-level headings in the root document, then Sphinx treats those headings as chapter titles (manual) or section names (how-to guide). For example, consider this index page:

Heading A
=========

Heading B
=========

.. toctree::
   :caption: TOC Caption

   about

In this case, “Heading A” appears as the first chapter title / section name, and “Heading B” appears as the second chapter title / section name.

Chapters and Sections

The LaTeX report document class contains chapter elements, followed by section, subsection, subsubsection, and paragraph elements. The LaTeX article document class, in contrast, starts at the section level.

As noted above, if the root document (index.rst) contains one, and only one, top-level heading, then Sphinx begins by using the next level of reStructuredText headings for chapter elements (LaTeX report / Sphinx manual) or section elements (LaTeX article / Sphinx how-to guide). If the root document contains multiple top-level headings, then Sphinx uses those headings for chapter / section elements.

Sphinx nests headings of files in toctree directives beneath the preceding heading level. In other words, when creating a Sphinx manual from the project above, Sphinx

ignores “Heading A”
renders “Heading B” as \chapter{Heading B}
renders “Heading C” as \section{Heading C}
renders “Heading D” as \subsection{Heading D}

If, however, “Heading A” and “Heading B” are marked as the same level, then Sphinx

renders “Heading A” as \chapter{Heading A}
renders “Heading B” as \chapter{Heading B}
renders “Heading C” as \section{Heading C}
renders “Heading D” as \subsection{Heading D}

If you use the “how-to guide” theme (LaTeX article), then Sphinx instead begins with section elements rather than chapter elements.

Section Numbering

By default, LaTeX engines number sections to a depth set by the LaTeX secnumdepth counter. As detailed in the unofficial LaTeX reference manual, the default value of secnumdepth is 3 for the report document class and 2 for the article document class. This means that the LaTeX chapter (only in Sphinx manuals / LaTeX report documents), section, and subsection elements are numbered. You can change the value of the secnumdepth counter to any value X in the LaTeX preamble with:

\setcounter{secnumdepth}{X}

You can use the latex_elements option in conf.py to add this command to the LaTeX preamble. For example, to set the depth to 5, use:

latex_elements = {
    "preamble": r"""
\setcounter{secnumdepth}{5}
""",
}

The LaTeX document generated by Sphinx contains a custom command, \sphinxtableofcontents, that instructs the LaTeX engine to build a table of contents. By default, Sphinx gives the table of contents a title: “Contents.” You can change the table of contents title by adding a caption to the toctree directive. The example project above has a caption:

.. toctree::
   :caption: TOC Caption

   about

Sphinx therefore adds the following to the preamble:

\addto\captionsenglish{\renewcommand{\contentsname}{TOC Caption}}