search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

sphinx-apidoc to generate headings for each class in separate-file mode #6788

Open ben-spiller opened 5 years ago

ben-spiller commented 5 years ago

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.

ben-spiller commented 5 years ago

Didn't manage to work around it - apidoc templates are limited and don't allow customization of the contents (e.g. classes) of a module, and autosummary doesn't do the job either. I'll need to code something custom from scratch to do the introspection and generate appropriate .rst files... so this feature would indeed be very helpful.

psifertex commented 3 years ago

I've implemented something that might do what you're looking for in a project here: https://github.com/Vector35/binaryninja-api/blob/dev/api-docs/source/conf.py#L39-L97

I first auto-generate using the inspect module the various -module.rst files and then those use automodule to do the rest. You can see the results here:

https://api.binary.ninja/ (notice how each class gets its own TOC entry when you open a particular module you see all classes. Unless you mean you want the TOC to show all classes from all pages?

ben-spiller commented 3 years ago

Thanks, looks interesting.

In the end I had already written an extension to do what I wanted here: https://pypi.org/project/sphinx-autodocgen/

Though would love this capability to be in sphinx itself eventually

psifertex commented 3 years ago

Thanks for the link, I'll have to check it out. I agree, this seems like such a common use-case that having it be first-party makes a ton of sense. It was intimidating trying to first get started with Sphinx and not having an easy time figuring out how to document a whole project automatically.