Annotated Sphinx toctree

Question

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:

Being Foo — W. Robert Foo created the first metasyntactic variable in 1857 and we've been using it ever since.
Doing Bar
Thinking Baz

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
– Begoña Álvarez de la Cruz, Commented Sep 11, 2020 at 11:08

geographika · Accepted Answer · 2017-04-19 10:29:39Z

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?

answered Apr 19, 2017 at 10:29

geographika

6,5284 gold badges43 silver badges59 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

Jason S Over a year ago

yeah, this information belongs in foo.rst, not the top-level .rst file.

geographika Over a year ago

@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 stackoverflow.com/questions/33637299/modify-sphinx-toc-tree

MRule Over a year ago

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?

Collectives™ on Stack Overflow

Annotated Sphinx toctree

1 Answer 1

3 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

3 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related