Create a guide on integrating documentation generated from source code into your docs

[davidfischer]

We should have a guide on generating documentation from source code and integrating it into a larger docs project. Ideally we would have this for Sphinx and MkDocs but prioritizing Sphinx first is reasonable. We should discuss the trade-offs so people can make the right decision for their project. We can also perhaps briefly mention that autogenerated docs are not a substitute for other docs but that both are helpful.

There are a few packages here for generating documentation from source code:

• autodoc - Autodoc is built-in to Sphinx and only works on Python code. It also imports the code so all dependencies of the code must be installed to build the docs. Autodoc can be combined with third-party packages like sphinxcontrib-httpdomain to have API documentation from source code (example)
• Sphinx-autoapi - Sphinx AutoAPI is a third-party package (under the RTD umbrella) for parsing source code and getting documentation from docstrings/comments. It works on languages other than Python and it doesn't have to import Python code to generate docs for it although there's some things Autodoc can do that AutoAPI can't. At the same time, for a project with a lot of dependencies, not having to install all those dependencies to build the docs has a lot of advantages (faster builds, fewer resources, etc.)
• Swagger - There are a few options for integrating Swagger with Sphinx (and MkDocs??). Swagger is primarily for REST API documentation.
• There may be more.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[astrojuanlu]

I wrote a chapter on autodoc as part of the upcoming new Sphinx tutorial https://github.com/sphinx-doc/sphinx/pull/9534 and I also included a brief mention of autosummary. I think that, after review, it will become a good foundation for other materials.

In particular, we could focus on:

• Suggesting sphinx-autoapi as an alternative to autodoc (or should I say autodoc + sphinx-autoapi?)
• Writing a guide on REST API docs with Sphinx. I did a quick search and found very old extensions (last updated 2017-2018) that didn't give me a lot of confidence. The newest one I saw is https://github.com/sphinx-contrib/openapi, but unfortunately issues are starting to pile up.