9. Writing and Publishing Documentation

This section describes how to write and publish documentation for GDA and Scisoft.

If you just want to view the manuals, they are available at the alfred.diamond.ac.uk/documentation/ website.

See also

Sphinx
documentation generator
reStructuredText
markup language used by Sphinx
CheatSheet
Restructured Text (reST) and Sphinx CheatSheet
sphinx-dev
Google Group

9.1. Checking out the documentation source

9.2. Structure of a manual

9.3. Building and Publishing

Make your changes by editing the markup (in .rst files) using any suitable editor (eg Eclipse text editor). Unfortunately, there is no suitable WSYWIG editor available.

To build a manual using the Eclipse IDE:

Use the External Tools icon external_tools on the Launch toolbar, or go to Run ‣ External Tools and select the manual
(the output from the build process, including any error messages, appears in the Console view)

To build a manual from the command line:

cd documentation.gda/Infrastructure_Guide/            # specify the appropriate directory for your manual
make clean all CONTEXT=diamond                        # or, e.g., "make html", "make clean pdf", etc.

The built manual can be found in:

  • The built manual HTML is written to project_directory/manual_name/build/html/contents.html and can be viewed within Eclipse, or in an external web browser
  • The built manual .pdf is written to project_directory/manual_name/build/pdf-papersize/manual_name.pdf

To publish your changes, simply check them back in to the repository

  • Please make sure that your changes build without errors (for both HTML and .pdf) before checking them in to the repository
  • Do not check in the build directory, only your changes in the source directory
  • Once checked in, new versions of the manuals will be automatically built and published to the web sites (this normally takes around 10-15 minutes)
  • You will receive an email once the build/publish job completes or fails, provided the build server knows the email address associated with your FedID

9.3.1. Notes on the automated build

The build and publish process is performed by the various Jenkins jobs named *.documentation.manuals. To see how this works, look at:

  • The Configure page for the specific job (this points to the script which does the actual build and publish)