Side bar navigation incomplete in Sphinx

Question

I made a Sphinx project with an index file and two other rst files called firstdoc.rst and seconddoc.rst. My index.rst has the following toctree:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   firstdoc
   seconddoc

I ran make html after adding the firstdoc.rst and then again after adding seconddoc.rst.

Now when I transfer the _build/html directory to a server I find that the index page has a side bar which lists both the firstdoc and seconddoc pages. The firstdoc page does not list any pages in the side bar. The seconddoc page lists the firstdoc page but not the seconddoc page in the side bar.

I want all the pages to list all the pages in the sidebar. How should I go about this?

Edit: If I edit the firstdoc.rst and seconddoc.rst files and then run make html and then transfer firstdoc.html and seconddoc.html to the server then I get what I want. That is all the pages are shown in the sidebar of all the pages. This seems very unsatisfactory as it means every time I add a new page to my project I have to edit all the existing pages in the project in order for them to include the new page in their side bar. Is there a more convenient way?

Answer 1

The general rule is that the .. toctree:: on your index page (the page set as master_doc in conf.py) will control the structure of the sidebar on all documents, so the :maxdepth: option set there will control the sidebar's depth as it displays on all pages.

Make sure you run make clean and double check all the build files are deleted, it should work. Your note that editing the files before the build solves it hints that intermediate build files are being cached.