On Python Documentation with Sphinx[
I’ve been exploring the Python documentation system for ReadTheDocs with Sphinx. It could be that I’m dense, but the
sphinx-quickstart command seems horribly divorced from most of the automagic documentation goals of the Sphinx project. After following several guides1, 2 I noticed that only an index.rst had been created in the
_sources directory. Brandon’s guide suggests that adding your module to either your PYTHONPATH or to your conf.py before
make html would lead to autodoc recognizing your package. I wasn’t able to get this to work on OSX Sierra using a virtualenv. After looking through more tutorials, I encountered some suggestions for the
sphinx-apidoc command, without actual invocation details.
So it seems that to generate the documentation for a new module, you must run
sphinx-apidoc to generate the module’s
.rst file, and then run
make html to generate the html. It’s remarkably easy when you figure it out, but kind of poorly documented considering the docs come from Sphinx and RTD directly.
I suppose I assumed that
sphinx-quickstart would have an option to specify existing module/lib directories and automatically bootstrap a Python package/project to make it a simpler experience. I highly recommend sphinx-mode.el for Emacs users, to automatically generate Sphinx-format docstrings and capture most of the function signature.