How to Write the Wiki

The goal of this page is to document how this wiki is written, with the goal of helping future users document their code and maintain the current content.

The documentation framework

The backbone of this wiki is reStructuredText, which is simply plain text with a special markdown syntax. ReStructuredText is written to .rst source files, which are then compiled to produce .html files.

The “compiler” used is Sphinx (http://www.sphinx-doc.org/en/stable/), a documentation generator widely used by the Python community but also useful for other software projects. Sphinx allows the user separate style work from documentation work, in a similar way that LaTeX documentation works. This wiki uses a style provided by Read the Docs (https://readthedocs.org/), again widely used by a number of software projects due to its beauty, flexibility and cross-compatibility with a number of vieweing devices.

Ultimately, the produced .html files can be then hosted online and viewed under a web browser. This wiki is hosted under the Github Pages framework, which allows easy hosting of the .html files, an integrated backup solution and collaboration with git version control.

A top-level view of the documentation framework can be seen in the following figure:

../_images/wikiProcess.jpg

Installing the documentation tools

The documentation using reStructuredText and Sphinx requires relatively few tools and these are very easy to install. At the moment, documentation support is only given to users with a Debian linux distribution. If you have any other OS, you can make use of a Virtual Machine which will allow you to use a different OS without partitioning your drive. Please refer to Vmware Workstation Player (https://www.vmware.com/go/downloadplayer) or Oracle VirtualBox (https://www.virtualbox.org/wiki/Downloads) for virtual machine solutions.

1. Install Python 2.7

Python 2.7 is necessary to run Sphinx. Please note that this may be already included in your system. You can install it using the following command:

sudo apt-get install python
2. Install Sphinx

You can install the Sphinx documentation generator using the following commands:

sudo apt-get install python pip
pip install sphinx sphinx-autobuild

3. Clone the wikiSource repository

4. Clone the gh-pages repository

Wiki style guide