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