Documentation building and hosting

MkDocs and Github pages

MkDocs

The documentation is generated with MkDocs and it lives in docs/. The configuration is in mkdocs.yml (YAML format).

Markdown is an easy to learn format that is the default on Github and Stack Overflow. It is much easier on the eye than restructuredText - the established standard in the Python world. But it is also not as powerful. For more complex documentation Sphinx and restructuredText might be better suited.

Github pages

Github offers the option to host the project documentation on Github Pages. MkDocs has an inbuilt deploy functionality to push the documentation there. The pages are hosted as project homepage on github.io.

Working on the documentation

When you work on the documentation you can start a local server:

$ cd <path/to/your/clone>
$ tox -e docs-dev

This prepares an environment and runs mkdocs serve. You can do it directly already. Using tox here is a bit of overkill, but serves to demonstrate that you can use tox for automating and standardising all kinds of development tasks.

The documentation is now served on localhost:8000 and changes are automatically detected and the website is reloaded.

Tidy up the build in case of big changes or problems:

$ tox -e docs-clean

Deploying the documentation

If you have push rights for the repository, you can deploy the current documentation with:

$ cd <path/to/your/clone>
$ tox -e docs-deploy