Building and Checking the Quality of Documentation#

This document covers how to build the Training documentation and check it for quality.


Install Enchant to check spelling.


brew install enchant


sudo apt-get install enchant

Clone the Training repository, then create a Python virtual environment, install project dependencies, activate the virtual environment, and build HTML version of the Training documentation.

git clone
cd training
make html

Available documentation builds#

All build and check documentation commands use the file Makefile.

To see all available builds:

make help


html is the long narrative version used for the online documentation and by the trainer.

make html

Open /_build/html/index.html in a web browser.


presentation is an abbreviated version of the documentation. It is designed for projectors which are typically low resolution and have limited screen space. Trainers may present this version using a projector during a training.

make presentation

Open /_build/presentation/index.html in a web browser.

Authors should read Writing Presentation Markup for how to write markup for the presentation build.


linkcheck checks all links. See All links must be valid for configuration.

make linkcheck

Open /_build/presentation/output.txt for a list of broken links.


spellcheck checks the spelling of words. See American English Spelling, Grammar, and Syntax for configuration.

make spellcheck

Open /_build/spellcheck/ for each training's misspellings.


html_meta adds a meta data section to each chapter if missing. See HTML and Open Graph Metadata for more info.

make html_meta