Getting Started -- toctree

[Carl Gay]

Hi, I've been using Sphinx for a while, but have mainly just been adding content within the document structure setup by someone else (who has since left the project). Now I need to get to a deeper understanding of how Sphinx works so I can customize it a bit for the specific needs of our project, so I'm starting from the Getting Started page.

My first question is about the toctree directive. I am trying to figure out how to get a table of contents in the sidebar but not inline in the document, since the duplication is unnecessary. Here's what I did:

I ran sphinx-quickstart to create a new site. Then I added several headers and subheaders to index.rst so that toctree would have something to generate. Here's the entire index.rst file:

$ cat /tmp/site/index.rst 

.. abc documentation master file, created by

   sphinx-quickstart on Sun Oct 10 23:06:59 2021.

   You can adapt this file completely to your liking, but it should at least

   contain the root `toctree` directive.

Welcome to abc's documentation!

===============================

.. toctree::

   :maxdepth: 2

   :caption: Contents:

Dog

---

My dog has fleas.

Cat

---

My cat has paws.

CatSub

~~~~~~

This is a cat subheader.

CatSubSub

.........

This is a cat subsubheader.

Indices and tables

==================

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

With the above index.rst file, none of the headers showed up in the Table of Contents in the sidebar, nor did they show up inlined in the document itself. This is unexpected. 

Question: what is the purpose of toctree if it doesn't generate a table of contents based on the current document's headers? I feel that I still don't understand the model Sphinx is using for the toctree.

Then I reread the documentation on the toctree element and thought "maybe it requires at least one document to be listed in its contents section", so I added "index" as the sole element in the contents of the toctree, like this:

.. toctree::

   :maxdepth: 2

   :caption: Contents:

   index

Other than that, the document remained the same. There were three notable changes when I re-ran sphinx-build:

1. I got these warnings during the build:
   /tmp/site/index.rst:9: WARNING: duplicated entry found in toctree: index
   /tmp/site/index.rst: WARNING: circular toctree references detected, ignoring: index <- index
   
2. The sidebar contained the table of contents I expected. \o/  But the warnings make me think I'm not doing the right thing.
3. The table of contents was also inlined directly in the page, under "Welcome to abc's documentation". (Not what I hoped for, but I could probably live with it.)

Question: Is there a way that I can get the table of contents to appear in the sidebar but not inlined in the page at the same time?

I'm using Sphinx 4.2.0 and the default (alabaster) theme, if it makes a difference.

Thanks for any help you can provide!

-Carl

[Carl Gay]

This part I think is accomplished by using the :hidden: option. I'm still not sure about the warnings or getting the headings in the document that contains the toctree directive to show up in the ToC.