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