Sphinx section numbering for more than level 3 headings: .. sectnum::

Question

I am using Sphinx to generate pdf files from rst files. Sphinx automatically generates section numbers up to level 3 headings, as well as Table of Content up to this level. However, I want the headings at all levels being numbered and be in the TOC. In order to do that, I am trying to use .. sectnum:: (http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents). The result is not exactly what I expected:

1. There is a number 1. being added in front of all section numbers in both TOC and text, that is, instead of 1, it's 1.1, instead of 2, it's 1.2.

2. In both TOC and text up to the third-level heading, the section numbers sort of get repeated, i.e. there is a section number (a correct one) in front of the wrong one (with 1. added in the front).

Here is my sample rst file:

---

.. sectnum::




level 1: the first party
========================

level 1 desc: this document is about xyz

level 2
-------

level 2 desc

level 3
~~~~~~~~

level 3 content

level 4
^^^^^^^^

level 4 content

level 5
''''''''

level 5 content jflkasjfslkajf
asdfsafs

level 1: the second part
========================

fjsdafjskalfjslkafjksaljflksaj
fasdhfkjsahfjkhdsf

level 2
-------

level 2 desc

level 3
~~~~~~~~

level 3 content

level 4
^^^^^^^^

level 4 content

level 5
''''''''

level 5 content jflkasjfslkajf
asdfsafs

---

Here is the result of TOC:

(I took a shot of my pdf file to show the result, but I just found out that I couldn't post images because I need 10 reputation for that, this is my first time posting anything)

1 1.1 level 1: the first party
  1.1   1.1.1 level 2

2 1.2 level 1: the second part
  2.1   1.2.1 level 2

Here is the result of the text:

                     1.1 LEVEL 1: THE FIRST PARTY

level 1 desc: this document is about xyz

1.1 1.1.1 level 2

level 2 desc

1.1.1 1.1.1.1 level 3

level 3 content

1.1.1.1.1 level 4

level 4 content

1.1.1.1.1.1 level 5

level 5 content jflkasjfslkajf asdfsafs

As you can see, there is 1. added to the section number, and there is a repeated part for the headings up to level 3.

Answer 1

Sphinx seems to take the view that the whole project is one document, and every .rst file is one chapter of it; you can indicate the order of the files in your main .. toctree:: . I guess that's why you get the numbers. I'm guessing it's a pretty common use case not to want .rst files numbered, though, so maybe someone should propose that.

By the way, note that Sphinx explicitly does not support sectnum. Instead, they recommend you use the :numbered: parameter in the top-level .. toctree::. (http://sphinx-doc.org/rest.html)

Answer 2

I try your code rendered to HTML and it works fine.

maybe you can consider HTML format.

---

In addition,

.. sectnum::

and

.. toctree::
   :numbered:

I think they aren't different, depends on your design to choose.

• just want subsection to be numbered: sectnum
• entire project's heading with numbered (it will auto contain sub toctree) choose: toctree:: :number:

---

Learn more > toctree number