0

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).

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Baut
  • 59
  • 3
  • This is strange. You are supposed to get numbers only if the `numbered` option is used. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree (link to official docs). – mzjn Nov 16 '19 at 08:44
  • @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 Nov 16 '19 at 09:00
  • Do you completely clean out the old build when running Sphinx (`make clean html`)? Possibly related issue: https://github.com/sphinx-doc/sphinx/issues/591. – mzjn Nov 16 '19 at 09:05
  • That fixed the issue, thanks a lot! I'll edit the original post for others stumbling upon this thread. – Baut Nov 16 '19 at 09:14

1 Answers1

1

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.

Baut
  • 59
  • 3
  • If you have run `make clean html` (first clean, then build), it should not be necessary to execute `make html` after that. You could do `make clean` followed by `make html`. – mzjn Nov 16 '19 at 09:24