Annotated Sphinx toctree

3
votes

The usual use of toctree in Sphinx looks something like this:

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

and if, for example, foo.rst starts with a title heading "Being Foo", bar.rst starts with "Doing Bar", and baz.rst starts with "Thinking Baz" then you will get a nice table of contents that looks like this:

with links from each to the appropriate page.

My question: is there a way to annotate a toctree? For example, if I wanted to annotate the "Being Foo" heading with something like "W. Robert Foo created the first metasyntactic variable in 1857 and we've been using it ever since.", then I could put that text somewhere (hopefully at the top of foo.rst, but if not, then in the toctree directive) and the toctree output would look like this:

1
python-sphinxtoctree
Did you find a way to annotate the toctree within the source file, in your case, foo.rst? I am looking for the same feature, without writing in the toctree definition itself and losing the autotitle. Thanks! - Begoña Álvarez de la Cruz

1 Answers

2
votes

You can override the page title using the following syntax:

.. toctree::
   :maxdepth: 2

   Being Foo - W. Robert Foo created the first metasyntactic variable in 1857 <foo>
   bar
   baz

http://www.sphinx-doc.org/en/stable/markup/toctree.html?highlight=entries

However you'd then lose the auto-title, which may be the main part of your question?