Part VI – Documenting the TaskBuster Django Boilerplate

Next in our tutorial, we’ll talk about documentation. Although I’m sure our TaskBuster project is documented enough throughout this tutorial ūüôā

At this moment, our project has a functional home page that supports internationalization, localization and time zones. And it’s completely covered by tests ūüôā

However, we have prepared this project with more collaborators in mind. We want that someone can download what we’ve done so far, and use it as a Project Template for its own Django project.

Yess! An awesome Django Project Boilerplate!! 

But we need to document it well, so that anyone who downloads our project from an online repository has all the information to install it, configure it, and run it.

Let’s get to work!

The Outline of this part is:

We will use reStructuredText (reST) to write the documentation, a common markup format. For those of you who worked with LaTeX, is something similar. You write a plain text file without any special format, like

TaskBuster
==========

Welcome to the TaskBuster Documentation

and then you compile it. The result is a nice html file with a big title (TaskBuster) and a paragraph (Welcome to the TaskBuster Documentation). You can see more examples in¬†Read The Docs, where we will upload our final documentation for everyone to see ūüėČ

taskbuster_documentation

Don’t forget to document your Django app!

Another tool that we will use is¬†Sphinx, a python package that takes docstrings of your code files and includes them inside your docs, automatically!! ūüôā

Install and configure Sphinx

As we won’t use the docs in production, install Sphinx only in the developing environment (and if you want, also in the testing environment). Activate the virtual environment and type:

Looking at¬†the final message, you’ll see that you also installed the packages¬†docutils,¬†Jinja2,¬†Pygments¬†and¬†markupsafe¬†(and depending on your version, also alabaster, babel, six, snowballstemmer and/or¬†sphinx-rtd-theme). You should add them all in the environment’s requirements file, requirements/development.txt (remember to pip freeze to see the current version).

Go inside the taskbuster_project folder to configure Sphinx with:

Note: if you have a Mac and see the an error saying “ValueError: unknown locale: UTF-8”,¬†use this solution.

next, Sphinx will ask you different questions, and for each of them you will find the default answer between []:

1. Enter the root path for documentation.
> Root path for the documentation [.]: ./docs

This creates a docs folder inside the taskbuster_project folder, that will contain all the documentation.

2. You have two options for placing the build directory for Sphinx output.
Either, you use a directory “_build” within the root path, or you separate
“source” and “build” directories within the root path.
> Separate source and build directories (y/n) [n]: n

3. Inside the root directory, two more directories will be created; “_templates”
for custom HTML templates and “_static” for custom stylesheets and other static
files. You can enter another prefix (such as “.”) to replace the underscore.
> Name prefix for templates and static dir [_]: _

4. The project name will occur in several places in the built documentation.
> Project name: TaskBuster
> Author name(s): Marina Mele

5. Sphinx has the notion of a “version” and a “release” for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. ¬†If you don’t need this dual structure,
just set both to the same value.
> Project version: 0.1
> Project release [1.0]: 0.1.0

This is our first project version, thus the small number 0.1.0. Each time we fix some bug or minor error, we will increase the third number (0.1.0, 0.1.1, 0.1.2, etc), and each time we add a new functionality, we will increment the second number (0.1.0, 0.2.0, 0.3.0, etc).

6. If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language.
F
or a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language
> Project language [en]: en

7. The file name suffix for source files. Commonly, this is either “.txt”
or “.rst”. ¬†Only files with this suffix are considered documents.
> Source file suffix [.rst]: .rst

8. One document is special in that it is considered the top node of the
“contents tree”, that is, it is the root of the hierarchical structure
of the documents. Normally, this is “index”, but if your “index”
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: index

9. Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]: n

Now, we need to indicate the Sphinx extensions we want to add to our documentation. For now, we will only include autodoc, an extension that looks inside our project files for docstrings and imports them into the documentation:

10. Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n
> todo: write “todo” entries that can be shown or hidden on build (y/n) [n]: n
> coverage: checks for documentation coverage (y/n) [n]: n
> pngmath: include math, rendered as PNG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: n
> viewcode: include links to the source code of documented Python objects (y/n) [n]: n

11. A Makefile and a Windows command file can be generated for you so that you¬†only have to run e.g. ‘make html’ instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: n

If you’re using Windows, answer y to the previous question.
Sphinx docs structure

You’ll see that you have a docs folder with the structure shown in the right image.

Next, we need to edit the conf.py file. Open it and after the sys and os imports add the following:

Note that we are including the top folder, taskbuster_project, into the system path. This will tell Sphinx where it should look for your project files.

Next, go inside the docs folder and type:

you should see something like

So go inside the _build/html folder, and open the index.html file with your browser. You should see something like:

sphinx-html-index

Yeah, I know it’s quite empty, but we’ll fix that in a minute! ūüôā

By the way, it’s a good time for a commit:

The last one only if you have a remote repository, like Bitbucket or Github, with the alias origin.

Documenting the TaskBuster Django Project Boilerplate

Inside the docs folder, there is an index.rst file that contains the index of documentation. Let’s edit and add some content!!

This file describes the TaskBuster project and then, after the toctree directive, we are including two different files: requirements.rst and quick_start.rst, which are not yet created.

Let’s fix that!! Create both files inside the docs folder:

The requirements.rst file will include all the requirements necessary to use our Django Project Boilerplate, and the quick_start.rst section will explain how to use and personalize the Boilerplate (e.g., change the project name or the translation languages).

These files contain the following:

 

Next, run again the html builder to see the changes!

Did it work?!

Upload the Project on GitHub

Now that we have our boilerplate ready, we will upload it into GitHub, so that anyone can download it and use it. However, two things GitHub recommends to include in a repository are the files LICENSE, README and .gitignore.

In order to decide which license you want to use for a project on GitHub, you should read this GitHub article or the Choose a license website.

For the TaskBuster Django project boilerplate I will use the MIT license, and it will be a text file located in the root directory.

Next we will create the README.rst file (also in the root directory), with a similar content as the index.rst file.

We already have the .gitignore file ūüôā

Once we have these files, we need to create a new repository on GitHub and get its url (here, https://github.com/mineta/taskbuster-boilerplate.git).

Next, we add this repository as the github remote:

note: you can call the remote “origin” instead of “github” if you want to, but I choose this name to not confuse with the Bitbucket “origin” remote.

Commit your changes to your local repository:

and update it into the GitHub repository (as well as in your private Bitbucket repository):

Check the TaskBuster Boilerplate project on GitHub!

Upload your Docs on ReadTheDocs

First, create an account in ReadTheDocs¬†if you don’t have one yet.

Next, you can connect your GitHub account and import your project’s docs from there.

And you just need to import your desired project from GitHub, and create your docs in ReadTheDocs!

You can see the results here!

What’s next?

Now, you can check or download the full code developed in this tutorial in the GitHub repository: TaskBuster Boilerplate

Or continue with this tutorial and configure your database. But which one will you use?

That’s all for this part!

Don’t forget to give it a +1 if useful, and share it with your friends! Thanks! ūüôā

Google+TwitterLinkedInFacebookReddit

Please, add +Marina Mele in your comments. This way I will get a notification email and I will answer you as soon as possible! :-)