Markdown cell output headers are not in TOC

[jtf621]

@jtf621 I've closed this issue because the missing headers are not missing anymore.

Please create a new issue for those headers not being part of the TOC.

Originally posted by @mgeier in https://github.com/spatialaudio/nbsphinx/issues/152#issuecomment-354082265

[jtf621]

I am trying again to generate markdown output that will appear in the sphinx TOC.

from Ipython.core.display import Markdown
h1 = 'This is a TITLE'
Markdown(f"# {h1}")  

when I have the above code in a cell and run it through the sphinx tool chain, the h1 header does not appear in the TOC.

If instead I use jupyter nbconvert to convert the .ipynb file to a .rst file, the resulting sphinx build will show the h1 in the TOC.

See #152 for more discussion.

[mgeier]

Thanks for creating this issue, I hope somebody will fix this!

[1kastner]

I just stumbled over this behavior in an up-to-date version. I tried to understand what is going on in https://github.com/spatialaudio/nbsphinx/blob/master/src/nbsphinx.py but reading and comprehending close to 2400 lines of code is no joke. @mgeier is there a chance that in the future this code is split up into several files, each dealing with specific concerns? That would make it much easier to contribute.

I hypothesize that this issue exists because first the document structure is built up. In this scope, all Jupyter Notebooks that are part of the documentation are identified and added to the TOC. Only then they are executed one-by-one. We would need to add the generated titles to the TOC manually afterwards because the automated set-up phase is over. @mgeier does that sound plausible to you as a first guess?

[mgeier]

@1kastner

I've moved the first part to its own issue: #667.

About the second part: I don't really know how the TOC is created. I've written my speculations at https://github.com/spatialaudio/nbsphinx/issues/152#issuecomment-353715736, which references #153.