Make sure a dynamically generated title is included in the TOC tree

[Marvin Kastner]

Hello there,

I have previously posted this question at https://groups.google.com/g/sphinx-users/c/LAZmNzd2D9M but thought that maybe this mailing group might be even more appropriate. Sorry in case you read this mail twice now.

How can I make sure a dynamically generated title is included in the TOC tree? This question came up in a discussion at https://github.com/spatialaudio/nbsphinx/issues/315. The summary and context goes like this: the Sphinx extension nbsphinx allows to write documentation  in Jupyter Notebooks. That's very nice and allows to run code in the docs. The output is also visualized and included in the docs. Thus, programmatically Markdown can be generated as output (Jupyter Notebook display function) which is then translated to its equivalent reST represenation. This dynamic content generation works fine but it has one limitation in its current implementation - the generated titles are not listed in the TOC and/or menu bar! They somehow go missing or most likely were never added to it in the first place?

Is there a canonical way how to add a dynamically generated title to the TOC? I mean some kind of dev API that serves that purpose? Or is there a somehow better way?

Best wishes
Marvin Kastner