Sphinx is a great tool for documenting Python, but its remarkably difficult to get started with, and (oddly enough) hard to find a good beginner’s tutorial for.
sphinx-quickstart, which will start you through the process, and interactively ask you questions, and make a
docs/conf.py and a
docs/Makefile for you. I don’t remember how I answered the questions.
I like to put docs in a
docs folder, which is then where
sphinx-quickstart will create a configuration file named
conf.py and a
Makefile. Then I like to have something like the following:
This is a standard README, that will appear on the Github page and in the documentation index file.
It should have a few sections:
This is the “welcome page”. It has two parts: the introduction (sourced from
README.rst), and the
Table of Contents. Here is source for it:
This will include the
README from above, and add links to
docs/example-usage.rst (make that yourself) and
docs/api.rst (see below).
This will tell Sphinx to auto-generate documentation from the module.
Or for more options,
You can also then use Read the Docs to host documentation; it will even pull from Github and build the documentation for you.
This was based on spack.