How to prevent automatic toctree entry numbering?

Question

I am building my documentation with Sphinx, to use with readthedocs.io. So far this always worked well. I'm orienting myself at the (in my opinion) excellent documentation of the godot engine.

Since I appreciated the titles in the documentation of the godot documentation, I tried to replicate these, by first having a look at the way they did it. Here's the link to the source for their index file. (Note: the relevant section is at the end of the document)

This seemed reasonable, as they used multiple toctrees, to give every toctree a caption.

When I do the same however, sphinx seems to automatically number my sections, something I do not want. The toctrees do not contain the :numbered: tag.

Here's a code sample, explaining how my toctrees are structured in principle:

.. toctree::
    :caption: Section 1

    Entry1
    Entry2

.. toctree::
    :caption: Section 2

    Entry2

The expected result would be similar to the godot documentation, with sections having titles but no numbers. Instead I am getting numbers, which seem arbitrary to me:

Section1
    1.Entry1
    2.Entry2

Section2
    1.Entry1

I can't find anything in the godot documentation explaining why they do not have these numbers, and I can't find any mention of it in the Sphinx toctree documentation either.

Any help or pointers towards help are greatly appreciated, thank you for your time.

Edit: Uploading the repo, with the built static html files to readthedocs.io seems to remove/fix the numbering. It persists in the local built though (the index.html file I built with sphinx in the first place).

This is strange. You are supposed to get numbers only if the numbered option is used. See sphinx-doc.org/en/master/usage/restructuredtext/… (link to official docs). — mzjn
@mzjn, That's why I'm here, unfortunately. I've read through the documentation, and nowhere does it mention my issue. Similarly, I didn't find other people with the same issue online. The good news is after uploading to readthedocs.io, the numbers are gone (as they should be), the bad news is it is still happening in my local html file that I built with sphinx within the gitlab repo. At least it doesn't affect the end product. — Baut
Do you completely clean out the old build when running Sphinx (make clean html)? Possibly related issue: github.com/sphinx-doc/sphinx/issues/591. — mzjn
That fixed the issue, thanks a lot! I'll edit the original post for others stumbling upon this thread. — Baut

Baut Baut · Accepted Answer · 2019-11-16T09:19:30

The answer to the question, courtesy of mzjn (see comment thread):

A rebuild of the project solved the issue. This can be done by entering

make clean html

in the console, fixing the weird numbering issue.

The relevant github issue can be found here.

This may possibly be caused by sphinx trying to find changes in the code and update these, instead of rebuilding the project every time. In this instance it did not update the toctree correctly.

How to prevent automatic toctree entry numbering?

1 Answers