Can Sphinx Section Numbering Skip Certain Sections (like a title)?

Question

I am making a series of design documents in Sphinx and I would like to include them together in a toctree and have the sections within the documents numbered. I know that I can use .. sectnum:: to number all sections in the child pages. However, Sphinx/rst numbers the title of the page (which is really just the first section) and the table of contents ends up looking like:

Table of Contents
    1 Design the First
    2 Design the Second

and each child page looks like:

1 Design the First
1.1 First Section
1.2 Second Section

What I want is a table of contents on my index page that just lists the title

Table of Contents
    Design The First
    Design the Second

and child page that look like

Design the First
1 First Section
2 Second Section

Is there a way to have a title that shows up in the TOC as well as on the top of a child page which does not end up being a numbered section?

Answer 1

I don't know what you ended up doing, but I wanted to do the exact same thing! I had the following setup:

index.rst

.. toctree::

   assignment
   library_api

I only wanted the assignment part to have numbers, so either could have done two separate toctree with one using :numbered:, or put at the top of the file

.. sectnum::
   :start: 0

Giving of course the exact problem you mention -- my top-level title was Assignment Writeup, so that was 0 and everything below it in subsections was 0.x e.g.

Assignment Writeup
==================

First Task
----------

Second Task
-----------

gives

0. Assignment Writeup
    0.1 First Task
    0.2 Second Task

as it turns out, there's an easy hack you can do. It makes things more modular than probably desired, but "add a layer of indirection".

So now I have assignment.rst and assignment_writeup.rst. assignment.rst just basically has a title and a toctree:

Assignment Writeup
==================

.. toctree::
   :maxdepth: 4

   assignment_writeup

then take all sub-sections and put them in assignment_writeup and "upcast" their heading level. So I now take all subsections and make them sections, and subsub and make them sub.

.. sectnum::
   :start: 0

First Task
==========

^^^ === instead of --- now

Second Task
===========

and we now finally have

Assignment Writeup
    0. First Task
    1. Second Task

kind of dubious, but this was the only way I could achieve it x0 I wonder what you did between asking this and now? Hopefully somebody will see this and benefit one day!

Note: this has undesireable side-effects. The Assignment Writeup shows up on its own page, with just Links to the indirect document. Not sure which is worse honestly...