Search code examples
python-sphinxrestructuredtextsectionstoctree

Prevent sphinx from restarting section numbering every file

I've got my index file set up like so:

Doc Title
==============================

..toctree::
   :maxdepth: 3
   :numbered:
   :caption: Contents

   01_file1
   01.3_file2

If the contents are thus...

01_file1.txt:

Level 1 section title
--------------------------------------------

Level 2 section title
............................................

Another Level 2 section title
............................................

and for 01.3_file2.txt:

A third Level 2 section title
............................................

I would expect this because Sphinx treats everything as a single document:

1. Level 1 section title
  1.1 Level 2 section title
  1.2 Another Level 2 section title
  1.3 A third Level 2 section title

But instead I get this:

1. Level 1 section title
  1.1 Level 2 section title
  1.2 Another Level 2 section title
2. A third Level 2 section title

I'm guessing this is because Sphinx (or maybe reST/Markdown?) restarts implicit heading levels with each new text file. Is there a way to get what I actually want?

Quoting the reST documentation...

Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle, the third will be a subsubtitle, and so on.

Solution

  • The parent file determines the heading level of its included children. To achieve the desired effect, remove 01.3_file2 from index, and place an .. include:: 01.3_file2 in 01_file1.txt at the point where you want to include it.

    index:

    Doc Title
==============================

..toctree::
   :maxdepth: 3
   :numbered:
   :caption: Contents

   01_file1

    01_file1.txt:

    Level 1 section title
--------------------------------------------

Level 2 section title
............................................

Another Level 2 section title
............................................

.. include:: 01.3_file2.txt

    01.3_file2.txt:

    A third Level 2 section title
............................................

    Results in:

    1. Level 1 section title
  1.1 Level 2 section title
  1.2 Another Level 2 section title
  1.3 A third Level 2 section title