2. Quick Guide

This is a quick startup guide which contains information on how to install/setup/use Sphinx and generate the documentation in html format. The minimum steps for updating the documentation are the following:

  • Install Sphinx. The section describing the configuration of Sphinx can be skipped since it has already been prepared.

  • Update documentation by editing <root_folder>/source/file.rst

  • Run make html.

2.1. Sphinx installation

2.1.1. Prerequisites

  1. Python 2.7 which can be downloaded from here:

https://www.python.org/download/releases/2.7/

  1. pip package management which can be downloaded from here:

https://pip.pypa.io/en/stable/

2.1.2. Installation via pip

$ pip install Sphinx

2.2. First steps with Sphinx

Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you.

Just run:

$ sphinx-quickstart

More info can be found here:

http://www.sphinx-doc.org/en/stable/tutorial.html

2.2.1. Setting up the Python environment in Windows

Should any issue with Sphinx commands arise, the first thing to check is whether the Python enviroment has been set up correctly.

  • Navigate to: Control PanelAll Control Panel ItemsSystem.

  • From the left side panel choose: Advanced System Settings.

  • In the System Properties window that opens select the Advanced Tab and then click Environment Variables.

  • Update PATH variable with the following entries C:Python27;C:Python27Scripts if not so.

  • Press OK.

2.3. Generating html documentation

Change directory to root_folder and run:

$ make html

2.4. Source code of the documentation

The source code of the documentation is written using the reStructuredText syntax. This is why the source files of the documentation use the extension .rst. More info regarding the syntax can be found here:

http://www.sphinx-doc.org/en/stable/rest.html#rst-primer

2.5. Using ReST Eclipse plugin

Editing of the *.rst can be done directly in SmartSnippets Studio.

2.5.1. Open .rst file in eclipse

  • Open file.rst. Moving easily from chapter to chapter can be achieved by using the Outline on the right side.

  • Images should be added to media folder of each chapter and must be in .png format.

  • Generate the .html documentation as mentioned above.

  • Open index.html file to preview the documentation by the internal browser of eclipse.