readthedocs / readthedocs/sphinx-autoapi

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

Open
#302 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Needed: Reproduction Case
Dominant language
Python
Stars
494
Forks
147
Avg merge
9m
Merged PRs (30d)
1

Description

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!

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the local modules.rst template and reproduce the swallowed top-level section headers, including rst syntax in docstrings. Read the referenced Sphinx issue for context and trace how the generated documentation handles the document's top-level title. Done means legitimate section headers render without requiring a dummy title.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.