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
Python 2.7 which can be downloaded from here:
https://www.python.org/download/releases/2.7/
pip package management which can be downloaded from here:
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:
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.