sphinx-doc / sphinx-doc/sphinx
sphinx-apidoc to generate headings for each class in separate-file mode
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
I'm trying to use apidoc to generate documentation for a large project. Many modules are large with a number of classes in each so I use apidoc --separate mode to get them in distinct files.
The navigation pane on the left is pretty useless for navigating within my module, since the only entity that gets a heading is modules, which isn't super-useful when there's a single module in each file. Classes/functions do not have headings therefore don't show up in the navigation pane, so can be hard to locate in a large file.
Describe the solution you'd like
It'd be great if a heading could be generated for each class and (non-class) free function, so the nav pane would make it easy to jump to the one the user is interested in.
Ideally this should be an option on "automodule" so people can enable it if desired whether they're using single-file apidoc mode or not.
Describe alternatives you've considered
I'm looking at implementing a workaround using apidoc templates or autosummary to provide links at the top of the page... which will be painful but I imagine I'll get there eventually. However this feels like something that could fairly straightforwardly be provided in the box, so worth considering as an enhancement.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing sphinx-apidoc --separate output with automodule behavior, focusing on how classes and free functions are represented. Review the apidoc templates and autosummary workaround mentioned in the issue. Done means an optional automodule setting generates navigation-visible headings in both separate-file and single-file modes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100