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.
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 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:
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"