On Sunday, October 10, 2021 at 7:52:00 PM UTC-4 Carl Gay wrote:
> 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 > <https://www.sphinx-doc.org/en/master/usage/quickstart.html> 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? > 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. > > 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 > > -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/c916ef4d-282a-4643-9f9b-adfeae70395bn%40googlegroups.com.
