[SUGGESTION] Create Full API Listing in Documentation

[marsfan]

Please only include one suggestion or features request per issue!

Is your feature request related to a problem? Please describe.
While the PiCamera2 Manual is very useful for learning how to use the library, it is lacking a full listing of all functions/classes/data types available in the library.

For example, in section 6.5 there is the sentence

All the capture and switch_mode_and_capture methods take two additional arguments

but no-where in the document do we have a listing of all of these methods, I have to search through the PDF for switch_mode, but even then, it does not mention all of the functions used in the examples.

Describe the solution you'd like
A full listing of all of the public functions/classes/data types in the picamera2 library. Either listed in the PDF manual, or available elsewhere (such as using ReadTheDocs, GitHub Pages, etc)

Describe alternatives you've considered
Just digging through the PiCamera2 source: Reading the source might not be as easy for everyone, and as picamera2 can't be easily installed on non-RPi devices, makes offline development harder.

Additional context
This might be as simple as just setting up Sphinx to automatically parse the source on each release, and pushing it to a website, which can be done in a day in my experience.

For an example, here's the documentation for the original PiCamera. See sections 9 through 16 in the sidebar.
picamera.readthedocs.io

[davidplowman]

Thanks for the suggestion, I certainly agree this would be a good thing! For it to have any chance of happening, I think we would have to take a route that is super easy to automate, and causes minimal extra effort when there are updates. If anyone has any experience of one of these tools (you suggested Sphinx?) and how to use them, that would be helpful to learn about. If it requires any changes or annotation of the existing source files, then PRs are welcome too! :)

I'll also have a word with our documentation team, to see what precedents there might be (the original Picamera was third-party software, so they may or may not want to take a similar route).

[marsfan]

@davidplowman I have used Sphinx before. Its really easy in my experience, basically being like Doxygen, but for Python (its even what Python's official documentation uses). You can set it up to automatically scan the codebase and extract all the function docstrings, and then use that to add documentation to the functions. Since the Docstrings already seem to use numpy syntax (the :param bit), I think it can be done without modifying the code at all. One catch is that the process to automatically generate the docs has to import the module, so you can't use it on a system that can't import it (like Windows for example)

https://www.sphinx-doc.org/en/master/