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 and activate a virtual environment, and install project dependencies.

git clone https://github.com/plone/training.git
cd training
python -m venv .
source bin/activate
pip install -r requirements.txt

Available documentation builds

All build and check documentation commands use the file docs/Makefile. Your working directory should be docs/ when issuing any of the commands.

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