Building and Checking the Quality of Documentation
Contents
Building and Checking the Quality of Documentation#
This document covers how to build the Plone Documentation and check it for quality.
Installation#
Install Enchant to check spelling.
macOS
brew install enchant
Ubuntu
sudo apt-get install enchant
Clone the Plone Documentation 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, pull in Volto documentation as a git submodule, build the docs, and view the results in a web browser by opening /_build/html/index.html.
git clone https://github.com/plone/documentation.git
cd documentation
make html
Available documentation builds#
All build and check documentation commands use the file Makefile.
To see the most frequently used builds, use the following command.
make help
Else you can open Makefile to see other build formats, including PDF.
html#
html is the HTML version of the documentation.
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.
linkcheck#
linkcheck checks all links.
See All links must be valid for configuration.
make linkcheck
Open /_build/linkcheck/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 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