Document Your Project

At this point we assume you already have created a new project, and established the Git repo for it etc.

Now we’ll walk through the steps for creating documentation for your project. We won’t get too far in the weeds here but will seek to establish a foundation to which you can easily add later.

The reason we cover docs so early in the game, is because as this tutorial project itself is being built, the docs in practice will come before most of the app code. So we are just documenting steps as we encounter them, while building the tutorial.

Install Sphinx

As is typical for Python projects, the docs we maintain within our project will use Sphinx, which in turn uses reStructuredText for the primary syntax. Sphinx offers a lot of convenience, and is configurable, can be extended etc.

You may not yet have Sphinx installed to your virtualenv, but we can fix that now. Run this command just to be sure:

pip install rattail[docs]

Sphinx Quickstart

Sphinx comes with a “quickstart” command, which you can use to walk through the process of creating a new documentation folder.

First change directory to your project’s source repo folder, then run the quickstart command like so. Note, this will create a ‘docs’ folder:

cd ~/src/rattail-tutorial
sphinx-quickstart --project rattail-tutorial docs

You will be prompted for a few things, mostly you can use the default option or provide some basic answer to each, and it will work out okay.

Before you go any further you may want to consider committing the generated docs code as-is, to help keep track of changes you make from there:

git add docs
git commit -m "Initial docs as generated by sphinx-quickstart"

Building the Docs

With the above steps complete, you should have a basic docs folder with some minimal default content, in reStructuredText format.

These docs must be “built” which generates HTML (or other formats) from the reST source. This is how you’ll (re-)build docs from now on:

cd ~/src/rattail-tutorial/docs
make html

This will generate HTML within the _build folder underneath the docs folder. You can then view these docs e.g. with:

firefox _build/html/index.html

Note that each time docs are built, it tries to avoid re-building things which haven’t changed since last build. It sometimes may be helpful to “clean” the docs build, i.e. wipe it out so the next build is forced to rebuild everything:

make clean
make html

Now if you check your git status, you’ll probably see the _build folder is considered “untracked” by git. However we don’t want git to concern itself with this folder at all, so we should ignore that, e.g. by doing:

cd ~/src/rattail-tutorial
echo 'docs/_build/' >> .gitignore
git add .gitignore
git commit -m "Ignore docs build folder"

And finally, there is another gotcha which you won’t notice until you clone your project’s source repo to another location, and try to build docs there. It’s not a real big deal, but you may see a warning when the docs are building, such as:

copying static files... WARNING: html_static_path entry '.../src/rattail-tutorial/docs/_static' does not exist

To prevent that, we’ll add a stub file to our repo which will ensure that folder always exists:

cd ~/src/rattail-tutorial
mkdir -p docs/_static
touch docs/_static/.keepme
git add docs/_static/.keepme
git commit -m "Add stub file to prevent docs build warning"

Writing Some Docs!

Again it may not make sense for you to do much of this, at this point in the game.

But while building this tutorial, all docs written up to this point have not been part of the project’s docs repo proper, but rather were created as simple ad-hoc text files. So our next step is simply to “transfer” all docs content created thus far, from these ad-hoc files, into the project docs folder.

This was a pretty manual process, then at the end we commit all changes:

cd ~/src/rattail-tutorial
git add docs
git commit -m "Transfer ad-hoc setup docs to tutorial project"