1.5. Building the GDA Developer and User Guides at Diamond

Building the Developer and User Guide is a two step process:

  1. Create/activate a Python 3 virtual environment

  2. Call make html in the document’s top-level directory

See below for details.

1.5.1. Create Python virtual environment

A Python virtual environment is used when building the GDA documentation as this provides an easy mechanism to ensure all Python modules required for the build are available and at expected version.

To create a Python 3 virtual environment called gda_doc_venv use the command:

module load python/3.10
python -m venv gda_doc_venv

The Python packages required to build the documentation using Python 3 are listed in the file gda-documentation/requirements_python3.txt, to install these into the created gda_doc_venv virtual environment do the following:

source gda_doc_venv/bin/activate
pip install -r <path_to_gda-documentation>/requirements_python3.txt

As Python 2 is no longer supported its use is not encouraged but a requirements_python2.txt is provided.

1.5.2. Build the documentation

Before building the documentation the documentation’s Python virtual environment (see above) must be activated e.g.:

source gda_doc_venv/bin/activate

To build the GDA Developer Guide (this document) do:

cd <path_to_gda-documentation>/GDA_Developer_Guide
make html

To build the GDA User Guide do:

cd <path_to_gda-documentation>/GDA_User_Guide
make html

The result of the build (i.e. the created website) can be viewed by opening the file build/html/contents.html in your favourite browser (the build/ directory is located in same directory in which make was executed).

Following any changes in the documentation source code it may be worth while checking for any broken links before pushing the changes to the gda-documentation repository, this can be done using the following command (in the same directory as make was called above):

make b_links

This will check for broken external and local links, automatically regenerate the source of appendix/documents_broken_links.md and rebuild the documentation updating Document’s Broken Links page.

N.B. Whenever building the documentation, remember to source the Python environment otherwise the build will fail.

For more information regarding the make process (including other Makefile targets available) see section Documentation Makefile and Scripts.