Documentation: a god-send when it exists, but always bottom of the priority list when creating your own projects. Fortunately, Sphinx is here to make it (a bit) easier to document Python projects. Here’s a quick, bare-bones run down of how to do it, and host it on readthedocs.
I think the easiest way is to just use pip
pip install -U sphinx
This way it’s packaged with your environment, and you can easily update or remove it as needed. The downside is you will have a separate install for each environment, so if disk space is a concern this isn’t the best approach, and you might want to choose another option here.
Navigate to your project directory, and create a
mkdir docs cd docs
Then you can run
sphinx-quickstart in this directory.
This will ask you a few questions, which you can answer yes to the defaults to in most cases. I like to separate the source and build directories to make managing the documentation with git easier.
Build the docs
It’s as simple as running
make with the format desired in the
docs directory. For example, for html:
Push to github
Your project is all up to date in source control, right? Good. (If not, go sort that out now).
Commit and push your new docs. You can ignore the
build folder and just add the make files and contents of the
Deploy to Read the docs
If you upload your code as-is to readthedocs your build will initially fail. This is because readthedocs by default assumes that the default master document is
index.rst. To fix it, just add this line anywhere within
source/conf.py (I stuck mine at the bottom with a ‘custom features’ comment).
master_doc = 'index'
Then go to readthedocs.org, sign up, and search for your repository. You should then be able to just follow the instricutions and build your beautiful documentation.
Subscribe via RSS