Building and Checking the Quality of Documentation#
This document covers how to build the Training documentation and check it for quality.
Installation#
Python#
Python 3.8 or later is required. A more recent Python is preferred. Use your system's package manager or pyenv to install an appropriate version of Python.
Vale#
Vale is a linter for narrative text.
It checks spelling, English grammar, and style guides.
Plone documentation uses a custom spelling dictionary, with accepted and rejected spellings in styles/Vocab/Plone.
Use your operating system's package manager to install Vale.
Vale also has integrations with various IDEs.
Plone documentation uses a file located at the root of the repository, .vale.ini, to configure Vale.
This file allows overriding rules or changing their severity.
The Plone Documentation Team selected the Microsoft Writing Style Guide for its ease of use—especially for non-native English readers and writers—and attention to non-technical audiences.
Note
More corrections to spellings and Vale's configuration are welcome by submitting a pull request. This is an easy way to become a contributor to Plone.
Clone plone/training#
Clone the Plone Training repository, and change your working directory into the cloned project.
Then with a single command using Makefile, create a Python virtual environment, install project dependencies, build the docs, and view the results in a web browser by opening /_build/html/index.html.
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.
livehtml#
livehtml rebuilds Sphinx documentation on changes, with live-reload in the browser.
make livehtml
Open http://0.0.0.0:8000/ 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.
vale#
vale checks for American English spelling, grammar, syntax, and the Microsoft Developer Style Guide.
See American English spelling, grammar, and syntax, and style guide for configuration.
make vale
See the output on the console for suggestions.
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
Overriding configuration options#
Both Sphinx and vale support overriding configuration options. The following examples serve as tips for spotting mistakes in your training.
In Sphinx, you can use the SPHINXOPTS environment variable to set configuration options of sphinx-build.
Syntax is in the following form.
make SPHINXOPTS="OPTION VALUE" BUILDER
The following example shows how to clean then build a live HTML preview of the trainings while suppressing syntax highlighting failures.
make SPHINXOPTS="-D suppress_warnings=['misc.highlighting_failure']" clean livehtml
You can also pass options to vale in the VALEOPTS environment variable.
In the following example, vale will not return a non-zero exit code when there are errors and will display warnings or errors only, not suggestions.
make vale VALEOPTS="--no-exit --minAlertLevel='warning'"