Documentation building and hosting¶
MkDocs and Github pages¶
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 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-auto
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