Building the documentation

This document describes how to build cgcam's html-based documentation using python/sphinx tools. Although python is probably already installed on your system, the sphinx extensions will most likely need to be installed. The following section describes how to check for the presence of python and how to install the sphinx extensions.

Install python if necessary

First check to see if you have python installed by issuing python --version and python3 --version. If one of these commands returns something like 'Python 3.7.6' then python is indeed installed. If python is not installed then you will get an error message something like 'python: command not found'. If python is missing, then install it using the appropriate package manager for your system. For linux this is most likely sudo dnf install python3 or sudo apt-get install python3. For mac os it is probably sudo port install python3 or sudo brew install python3. Once you think you have python installed, issue python3 --version again to make sure.

Install the python package manager (pip)

Depending on your system, the python package manager manager (pip) may or not have be installed automatically when python was installed. If you are using python2, issue pip --version, or pip3 --version for python3 to see if pip is installed. If not, install it using using your package manager. You may need to do a google search in order to determine the pip package name. On Debian based systems it is python3-pip and sudo apt get python3-pip will install it.

Install the sphinx extensions

The sphinx extensions are installed using the python package manager, pip. Use it as follows to install the sphinx components (replacing pip3 with pip if you are using python2)

sudo pip3 install sphinx==1.8.5
sudo pip3 install sphinx-rtd-theme
sudo pip3 install sphinx-copybutton

Note that sphinx version 1.8.5 is installed explicitly. It is important to do this since there appears to be a bug in later versions that results in incorrect list formatting when either the sphinx_rtd_theme or the sphinx_theme are used.

Build the documentation

Navigate to path_to_cgcam/cgcam/doc and issue make html. This command will produce html files for all of the various documentation chapters and sections and place them in the _build/html directory. You can then view the documentation locally using your browser's 'open file' option to load path_to_cgcam/cgcam/doc/_build/html/index.html. You can also copy or link the contents of the _build/html directory to a location on your web server in order to make the documentation more widely accessible. For example, you could create the directory /var/www/html/cgcam on your server and then copy the entire contents of the _build/html directory to that location. Once this is done, the documentation will be available at YourURL/cgcam.