Python `module.rst` top-level section headers get eaten by Sphinx

[TeoZosa]

I'm not sure what I'm doing differently (as I'm sure this would've been spotted by someone else much sooner), but top-level section headers are being swallowed by Sphinx. Combined with the fact that this also happens when parsing rst syntax in docstrings, I believe I've tracked it down to:

@shimizukawa in https://github.com/sphinx-doc/sphinx/issues/632#issuecomment-68563233:

From Georg Brandl on 2011-09-22 12:21:02+00:00

Your index.rst doesn't have a title, right? Basically Sphinx gobbles up the most toplevel title (which is then replaced by the document frontmatter).

I've been able to fix it with a hack where I add a dummy title (which, due to the above behavior, won't be rendered) to a local modules.rst template.

While this works, I'm curious as to why I'm the only one experiencing this issue and whether a better solution exists!

[holmboe]

@TeoZosa I was also blocked by this for a while and tracked it down today as well. Came to the same conclusion and added a hackish top-level header that will be slurped by Sphinx. In my case I am using myst-parser and building with make latexpdf. My root_doc is a Markdown-file with this at the top:

# INDEX

<!---
NOTE: The above header is required but will not be visible in the built document. If you skip it the first header in the first file in the toctree will be stripped out of the result. See https://stackoverflow.com/questions/27965192/python-sphinx-skips-first-section-when-generating-pdf and https://github.com/readthedocs/sphinx-autoapi/issues/302

--->

[AWhetter]

I don't understand the problem that you are describing. Do you have a small example that I can try out? Which section headers are being left out? The :py:mod: ones? Are you building to latex or to html?

[holmboe]

@AWhetter I will try to describe this from memory so bare with me.

Let's say you have one index.rst and one content file named content.rst. The headings from index AND the content file will be visible in the resulting HTML build. On the other hand, if you choose to build with latexpdf then only the heading from the content file will be visible, and the top-most heading from index.rst will be left out of the resulting document.

Problem 1: So there is a discrepancy in which headings are included in the build whether you choose HTML or PDF.

At this point my thought was to remove the top-level heading in index.rst altogether because it is not used in the PDF anyway. Doing so resulted in the top-level heading from content.rst to be slurped up and removed in the PDF instead. My workaround as described in my previous comment was to just leave a top-level heading in index.rst that will never be visible anywhere in the resulting PDF.

Problem 2: No heading should ever be slurped up, not in HTML and not in PDF.

I hope this is clear enough to reproduce this behavior.