Building and Checking the Quality of Documentation#

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

Installation#

Install Enchant to check spelling.

macOS

brew install enchant

Ubuntu

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 https://github.com/plone/training.git
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#

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#

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#

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#

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#

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

make html_meta