Project Documentation

Installing Python Sphinx

Python Sphinx is a tool that helps build documentation out of reStructured Text (rst) marked-up files.

You must have Python installed (we recommend Python 3.x).

Once Python is installed, you should have the pip utility installed natively (if not, go here). To check if you have pip:

$ python -m pip --version
pip 9.0.1 from C:\...\Python\Python36-32\lib\site-packages (python 3.6)

Once you checked pip is installed, run the command to install Sphinx:

$ python -m pip install Sphinx

We will also need the sphinx_rtd_theme for our docs:

$ python -m pip install sphinx_rtd_theme

Setup

Note

This should have been a one-time process setup by the administrator, and is only here for record keeping purposes. If you’re reading this, it’s setup.

All documentation related files are stored in the repository: CloudSevenConsulting.github.io. There are 2 branches of concern;

• master, which contains the built .HTML files as served on Github
• src, which contains the the source .rst files required for building
• doxy, which contains the DOxygen generated output; hopefully we don’t push this up all the time, this is just there to get you started - we will rely on the actual DOxygen build

1. We first make our src repo

$ mkdir CloudSevenConsulting.github.io
$ cd CloudSevenConsulting.github.io
$ git init .
$ git checkout --orphan src
$ echo 'build/' > .gitignore            # this will host the master branch

2. Setup your Sphinx project

$ sphinx-quickstart.exe

# press [enter] to all options
# EXCEPT:
#   - we want the ``build/`` and ``source/`` directories to be separate.
#   - we want MathJAX

$ git add --all
$ git commit -m "init src"

2. Write and Build with make html (see building below)

4. Now we set up the git repo for the master branch

$ cd build/html
$ touch .nojekyll       # This file is crucial for serving on Github
$ git init .
$ git add --all
$ git commit -m "init"

New Contributors

1. First clone the src branch

$ git clone https://github.com/CloudSevenConsulting/CloudSevenConsulting.github.io.git
$ cd CloudSevenConsulting.github.io
$ git checkout src

2. Now clone in the master branch

$ mkdir build/
$ cd build/
$ git clone https://github.com/CloudSevenConsulting/CloudSevenConsulting.github.io.git html

3. Clone in your doxy branch

   $ cd ../
   $ git clone https://github.com/CloudSevenConsulting/CloudSevenConsulting.github.io.git doxy
   $ cd doxy
   $ git checkout doxy
   

Building

Because of the way the branch gh-pages is set-up, a funny build process is required.

Note

Team to consider automating this with Python tool

1. Make your modifications in the src branch (you shouldn’t need to use the git checkout command at all, just cd).

2. If the indexes in your build must change (i.e. new files added/files moved) then a clean is required before build

   1. Do not use make clean, as this will remove the .git files.
   2. Manually remove all build files (everything in build/html excluding the hidden .git directory)
   3. Build the DOxygen xml

   Alternatively you can use the script CleanBuild.py

   $ python CleanBuild.py
   

3. Commit your source changes & build

   $ git add --all
   $ git commit -m "Update source..."
   $ git push origin src
   $ make html
   

Alternatively, use:

$ python MakeDocs.py

This does not clean, so make sure you do that!

4. Commit your changes in the master branch

   $ cd build/html/
   $ git add --all
   $ git commit -m "docs"   # who cares about commit messages here
   # git push origin master