Documentation using Sphinx and ReadTheDocs.org¶
Without documentation, however wonderful your software, other potential adopters and developers simply won’t be very interested in it.
The good news is that there are several tools that will make presenting and publishing it very easy, leaving you only to write the content and mark it up appropriately.
For documentation, we’ll use Sphinx to generate it, and Read the Docs to publish it. GitHub will be a helpful middleman.
If you have a package for which you’d like to create documentation, you might as well start producing that right away. If not, you can do it in a new dummy project.
Set up your working environment¶
As usual, create and activate a new virtualenv:
virtualenv documentation-tutorial [...] cd documentation-tutorial/ source bin/activate
The package or project¶
If you have an existing package to write documentation for¶
If your package is on GitHub already and you want to start writing documention for, clone it now using Git. And of course, start a new branch:
git checkout -b first-docs
You can merge your docs into your master branch when they start to look respectable.
If you don’t have an existing package that needs docs¶
If you don’t have a suitable existing package on GitHub, create
a repository on GitHub the way you did before. Call it
create a Git repository locally:
mkdir my-first-docs cd my-first-docs/ # Converts the directory into a git repository git init # Point this repo at the GitHub repo you just created git remote add origin firstname.lastname@example.org:<your git username>/my-first-docs.git # Create a new branch in which to do your work git checkout -b first-docs
And either way, create a
docs directory for your docs to live in:
pip install sphinx
It might take a minute or so, it has quite a few things to download and install.
sphinx-quickstart will set up the source directory for your documentation.
It’ll ask you a number of questions. Mostly you can just accept the defaults
it offers, and some are just obvious, but there are some you will want to set
yourself as noted below:
- Root path for the documentation
- Project name
<your name>'s first docs, or the name of your application
- Source file suffix
.rstis the default. (Django’s own documentation uses
.txt. It doesn’t matter too much.)
You’ll find a number of files in your
docs directory now, including
index.rst. Open that up.
Using Sphinx & reStructuredText¶
Sphinx uses reStructuredText. http://sphinx-doc.org/rest.html#rst-primer will tell you most of what you need to know to get started. Focus on the basics:
- headings (‘sections’, as Sphinx calls them)
- quoted blocks
- code blocks
- emphasis, strong emphasis and literals
Edit a page¶
Create an Introduction section in the
index.rst page, with a little text
in it; save it.
Create a new page¶
You have no other pages yet. In the same directory as
all-about-me.rst or something appropriate. Perhaps it might
############ All about me ############ I'm Daniele Procida, a Django user and developer. I've contributed to: * django CMS * Arkestra * Django
Sphinx needs to know about it, so in
index.rst, edit the
section to add the
.. toctree:: :maxdepth: 2 all-about-me
Save both pages.
Render your documentation¶
This tells Sphinx to render your source pages. Pay attention to its warnings - they’re helpful!
Sphinx can be fussy, and sometimes about things you weren’t expecting. For example, you well encounter something like:
WARNING: toctree contains reference to nonexisting document u'all-about-me' ... checking consistency... <your repository>/my-first-docs/docs/all-about-me.rst:: WARNING: document isn't included in any toctree
Quite likely, what has happened here is that you indented
.. toctree:: with four spaces, when Sphinx is expecting
If you accepted the
sphinx-quickstart defaults, you’ll find the rendered
docs/_build/html. Open the
index.html it has created in your
browser. You should find in it a link to your new
all-about-me page too.
Publishing your documentation¶
Exclude unwanted rendered directories¶
.gitignore? It’s really useful here, because you don’t want to
commit your rendered files, just the source files.
.gitignore, I make sure that directories I don’t want committed are
listed. Check that:
_build _static _templates
are listed in
Add, commit and push¶
git add the files you want to commit; commit them, and push to GitHub.
If this is your first ever push to GitHub for this project, use:
git push origin master
git push origin first-docs # or whatever you called this branch
Now have a look at the
.rst documentation files on GitHub. GitHub does a
good enough job of rendering the files for you to read them at a glance,
though it doesn’t always get it right (and sometimes seems to truncate them).
However, we want to get them onto Read the Docs. So go to https://readthedocs.org, and sign up for an account if you don’t have one.
You need to Import a project: https://readthedocs.org/dashboard/import/.
Give it the details of your GitHub project in the repo field -
email@example.com:<your git username>/my-first-docs.git, or whatever it is -
and hit Create.
And now Read the Docs will actually watch your GitHub project, and build, render and host your documents for you automatically.
It will update every night, but you can do better still: on GitHub:
- select settings for your project (not for your account) in the navigation panel on the right-hand side
- choose Webhooks & Services
ReadTheDocsunder Add Service dropdown
… and now, every time you push documents to GitHub, Read the Docs will be informed that you have new documents to be published. It’s not magic, but it’s pretty close.