python-docs

Reusable code for setting up Sphinx and a github.io website for a repository.

First time setup

1. Fill in the parameters in docs/PARAMS.yml.
2. Adjust the parameters in docs/Makefile to match those in docs/PARAMS.yml
3. Update links and titles in docs/index.rst with those appropriate for your project.
4. Create a gh-pages branch

   git checkout --orphan gh-pages
   git rm --cached -r .
   git commit -m "Initial commit" --allow-empty
   git push -u origin gh-pages

5. Install pip requirements (ideally in a virtualenv)

   virtualenv -p python3 venv
   source venv/bin/activate
   pip install -r docs/require.txt

6. Run make_docs.py

   python docs/make_docs.py

After the first time setup, all you need to run is python make_docs.py