How to add captions in Sphinx toctree without adding new documents?

Question

Okay, I'm using Sphinx Autosummary to generate documentation for some classes. There are three different types of classes and I want my sidebar to have three distinct sections, like if I was using the :caption: option in the toctree directive.

So I added separated my autosummary directive into three smaller directives, and I put a hidden toctree in between them like so:


Section 1

.. toctree::
   :hidden:
   :caption: Section 1

.. autosummary
   :toctree: stubs

   myclass
   anotherclass


Section 2

.. toctree::
   :hidden:
   :caption: Section 2

.. autosummary::
   :toctree:

   thirdclass

yields a sidebar like:

myclass
anotherclass
thirdclass

This doesn't work. The hierarchy of my index.html is exactly how I want it to look, but the sidebar is missing my Captions, they don't show up. When I add a page like self under any of these hidden toctrees, the caption shows up:


Section 1

.. toctree::
   :hidden:
   :caption: Section 1

   self

.. autosummary
   :toctree: stubs

   myclass
   anotherclass


Section 2

.. toctree::
   :hidden:
   :caption: Section 2

.. autosummary::
   :toctree:

   thirdclass

yields a sidebar like:

SECTION 1 (caption)
Documentation Home
myclass
anotherclass
thirdclass

This is what I was looking for, but I don't want to reference self or whatever. I just want the captions. How do I do this?

Are you using sphinx_rtd_theme? – mzjn Dec 14 '19 at 17:29 — mzjn, Dec 14 '19 at 17:29
Yes, I am using that theme. – Jay Parthasarthy Dec 15 '19 at 01:29 — Jay Parthasarthy, Dec 15 '19 at 01:29

mzjn · Answer 1 · 2019-12-17T16:19:03.327

4

The purpose of a toctree is to organize nested pages and it should have at least one entry (a filename). Otherwise, there isn't really any point in using it.

The markup below produces the wanted sidebar with sphinx_rtd_theme. I realize that it does not give you the index page that you want, but I cannot think of any other way of doing it. Put the autosummary directives in separate files and add each file as a toctree entry.

.. toctree::
   :caption: Section 1

   autosummary1

.. toctree::
   :caption: Section 2

   autosummary2

edited Dec 17 '19 at 16:19

answered Dec 15 '19 at 10:36

mzjn

48,958
13
128
248

What does this solution do to my index.rst? I assume users won't be able to see all of the classes on one page like I would prefer. – Jay Parthasarthy Dec 16 '19 at 17:03
Actually, it literally was... "Without adding new documents" is part of the question title. Thanks for your help. – Jay Parthasarthy Dec 16 '19 at 17:16
I would just like the sidebar structure to mirror my homepage structure. I don't want nested pages. If that's not possible in Sphinx-rtd, whatever. – Jay Parthasarthy Dec 16 '19 at 17:17
All i asked was for a way to make the sidebar structure match my home page structure. It does not seem crazy that one might want to include multiple captions in a single toctree. I only put toctrees with zero entries to try and hack in a caption without restructuring my entire homepage- the point of the question. If Sphinx does not support this option then you can just say so. No need for the tone of your comment. – Jay Parthasarthy Dec 16 '19 at 18:30
@mzjn it is not clear how this works. Do the autosummary files need to have their own pages? – jay Apr 18 '22 at 20:22
@JayStanley: Please ask a new question if you need help. – mzjn Apr 19 '22 at 03:32

How to add captions in Sphinx toctree without adding new documents?

1 Answers1