Sphinx¶

This documents current Sphinx behaviour for html and latex using the current implementation of toctree.

Parts and Chapters¶

The following toctree is contained in master_doc

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   :numbered:

   intro
   part1
   part2

with additional toctree directives in part1.md and part2.md

.. toctree::

    chapter1
    chapter2

produces the following html and pdf output

and conf.py contains latex_toplevel_sectioning = "part"

Limitations:

The intro document is interpreted as a part and doesn’t seem to be any direct support for frontmatter in the current sphinx approach. This is despite the top header being marked as level=1 using ==== rather than a level=0 using double ==== markup.

Important Notes:

Section levels seem to be inferred at the document level – so for each document the section level is set to the base level for the first header of the document regardless of any relative relationship outside of the document.

this means that chapter1.rst with:
```
Chapter 1
=========

Section1
--------
```
and a chapter2.rst with
```
Chapter 2
---------

Section 1
~~~~~~~~~
```
have the same level for Chapter 1 and Chapter 2 (and Sections) in the output.
The sphinx/mixed-sphinx-jb project allows for exploration of toc structures. It allows the ability to include frontmatter for html with numbering starting at the first part – but it doesn’t cater to abstract style number such as A.