How to reset numbered sections in Sphinx?

Question

I have several documents that are independant from each others:

index.rst
foo.rst
bar.rst
conf.py
Makefile

I would like to access foo.rst from index.rst, but I would like the two subdocuments to start their numbering at 1.

In index.rst I have:

.. toctree::
   :maxdepth: 2
   :numbered:

   foo
   bar

But, bar will take the number 2. and with this bar.rst I will get 2.1 Tomatoes.

=====
Title
=====

Tomatoes
========

Cucumbers
=========

and I would like this rendering:

1. Tomatoes
2. Cucumbers

How is that possible?

Answer 1

You cannot have it both ways. See Sphinx documentation for Section numbering under the toctree directive for the explanation:

Section numbering

If you want to have section numbers even in HTML output, give the toplevel toctree a numbered option. For example:

.. toctree::
  :numbered:

  foo
  bar

Numbering then starts at the heading of foo. Sub-toctrees are automatically numbered (don’t give the numbered flag to those).

Answer 2

I'm shocked that there isn't an easier way to do this!

It looks like shortly after asking this question, @nowox made this custom Sphinx extension which achieves the desired behavior.

To my surprise, I was still able to get the extension working in 2025! I simply copy-and-pasted the fix-secnum.py file into the top level of my Sphinx project (next to conf.py) and then added these lines to conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

extensions = ['fix-secnum']