4

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:

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Jason S
  • 184,598
  • 164
  • 608
  • 970
  • 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 Sep 11 '20 at 11:08

1 Answers1

3

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?

geographika
  • 6,458
  • 4
  • 38
  • 56
  • 1
    yeah, this information belongs in foo.rst, not the top-level .rst file. – Jason S Apr 19 '17 at 17:57
  • @JasonS - after digging into the source code it seems you can only really modify the TOC using an extension. I could read all the nodes of the TOC, and modify, but was unable to persist the changes, same as http://stackoverflow.com/questions/33637299/modify-sphinx-toc-tree – geographika Apr 20 '17 at 11:41
  • This is clumsy but ultimately solves the problem in my use case. However, I notice that neither HTML nor markdown syntax is respected for the description. Both are rendered verbatim, so there is no way to e.g. style "Being Foo" as bold and the rest of the text as normal weight? – MRule Oct 22 '22 at 11:34