Sphinx documentation

Aim

Reminder for creating and editing documentation.

Summary

Build documentation using Sphinx Documentation Generator. A little restructured text is shown as a reminder and the process of moving docs to gh-pages is detailed.

Install

sudo pip3 install sphinx
sudo pip3 install sphinx_rtd_theme
sphinx-build -h

Core framework

# /repos/GardenMonitor
mkdir docs
cd docs

Build documentation

# /repos/GardenMonitor/docs
sphinx-quickstart
# Follow the prompts
# I choose all default options except to have build and source in separate folders

Update theme by editing conf.py (in /repos/GardenMonitor/docs/source/conf.py)

html_theme = "sphinx_rtd_theme"

Restructured Text

Update index.rst (/repos/GardenMonitor/docs/source)

.. toctree::
        :maxdepth: 2
        :caption: Contents:

        /pages/summary
        /pages/setup
        /pages/docs
        /pages/database
        /pages/api
        /pages/xbee
        /pages/webserver

Add pages

# /repos/GardenMonitor/docs/source
mkdir pages
touch  summary.rst setup.rst docs.rst database.rst api.rst xbee.rst webserver.rst

Add titles

Chapter 1 Title
================

Add seealso box

.. seealso:: seealso text

Add note box

.. note:: note text

Add a warning box

.. warning:: warning text

Add images

.. image:: img/rpi.jpg
        :width: 600
        :align: center
        :alt: alternate text

        This is a caption

Make documentation

#/repos/GardenMonitor/docs
make html

Git

Add changes to github (assumes repo has been created)

git add .
git commit -m "added docs"
git push origin master

If gh-pages already exists then remove it and start again (mainly because I stuffed it up the first time)

# remove from remote
git push origin --delete gh-pages

# remove from local
git branch -D gh-pages

gh-pages

Host pages on github (you have to do this on every update to the docs)

# First time
git checkout -b gh-pages
touch .nojekyll
git checkout master docs/build/html
mv ./docs/build/html/* ./
rm -rf ./docs
git add --all
git commit -m "publishing docs"
git push origin gh-pages


# Updating
git checkout gh-pages
rm -rf *
git checkout master docs/build/html
mv ./docs/build/html/* ./
rm -rf ./docs
git add --all
git commit -m "publishing docs"
git push origin gh-pages