9. Documentation

There are three distinct guides that accompany the HLU Tool. All the guides are written using reStructuredText, their sources are stored on GitHub and they are available to view and download on ReadTheDocs.

User Guide

The user guide, available to view or download on ReadTheDocs at HLUTool-UserGuide, is for those who will be regular users of the HLU Tool but are not concerned with how to install or configure the tool or how to perform database administration.

Technical Guide

The technical guide, available to view or download on ReadTheDocs at HLUTool-TechnicalGuide, is for those of a more ‘techie’ nature. It contains details of how to install, configure, maintain and upgrade the HLU Tool and use and maintain the associated relational database.

Developer’s Guide

The developer’s guide (this guide), available to view or download on ReadTheDocs at HLUTool-DevelopersGuide, explains a little about how the HLU Tool source code is structured, what you may need to develop and support the tool and how to build and distribute it.

9.1. reStructuredText

9.1.1. What is it?

reStructuredText is is an easy-to-read, what-you-see-is-what-you-get plain text markup syntax. It is often used for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents (such as the HLU Tool guides).

reStructuredText can be written in any text editor, but some editors provide syntax highlighting and shortcuts to assist authors (see Tools & Extensions for some examples).

9.1.2. Further reading

For those unfamiliar with reStructuredText the following websites will provide some useful background reading material and references to help in authoring documents:

9.2. GitHub

9.2.1. Source Control

The source code for the documentation is stored on GitHub with each guide in a separate repository. Source control for the guides works in the same way as for the tool itself using Git and GitHub for Windows (see GitHub Source Control).

Tip

See HabitatFramework for a list of all the repositories on GitHub relating to the tool.

One of the benefits of reStructuredText is that documents written using it are readable in their ‘raw’ markup format. So the source code files for the guides can be viewed and downloaded directly using GitHub. However, the intended purpose of the markup is the conversion of reStructuredText documents into more structured data formats; that’s where ReadTheDocs comes in (see ReadTheDocs below).

9.2.2. Webhooks

The really clever trick is that once a change to a guide has been committed to GitHub, a Webhook notifies ReadTheDocs of the change. ReadTheDocs will then rebuild the documentation using the latest source of the documents.

Note

Webhooks allow external services such as ReadTheDocs to be notified when certain events happen on GitHub. When the specified events happen, such as a commit, GitHub sends a POST request to each of the specified URLs. The target system can then pull in the latest source and perform an action, such as rebuilding the documentation.

9.3. ReadTheDocs

9.3.1. What is it?

ReadTheDocs is an online documentation repository for the open source community. It supports Sphinx docs written with reStructuredText. Sphinx is a documentation generator which converts reStructuredText files into HTML websites and other formats including PDF. ReadTheDocs automates the process of building and uploading Sphinx documentation.

9.3.2. Building

By using a GitHub Webhook, ReadTheDocs will be ‘pinged’ when the source has been updated. ReadTheDocs will then rebuild the documentation using the latest source documents.

When each ReadTheDocs project (each guide is a separate project) is built it automatically builds separate HTML and PDF formats of the documentation. This provides users with alternative methods of viewing the guides, each with its own strengths and weaknesses.

9.3.3. Versions

ReadTheDocs supports multiple versions for each project, so for each release of the tool it can host a parallel release of each of the guides. To do this each guide would need to be updated (where appropriate) and then ‘tagged’ in GitHub (see GitHub Source Control). ReadTheDocs will then build HTML and PDF formats of the guide for the new version and continue to host this latest version together with all previous versions.

Tip

Which versions are available to users on ReadTheDocs can be configured on the Versions page in the Admin section for each project (guide).

9.3.4. Further reading

The ReadTheDocs documentation provides an introduction to those unfamiliar with ReadTheDocs features and explains the build process.