Building and Checking the Quality of Documentation
Building and Checking the Quality of Documentation#
This document covers how to build the Plone Documentation and check it for quality.
Install Enchant to check spelling.
brew install enchant
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
git clone https://github.com/plone/documentation.git cd documentation make html
If you are using an M1 Mac to build the documentation, there is currently an issue with pyenchant that throws an error that the enchant library can't be found.
This happens for example if you install Python 3 with
pyenv in the default M1 architecture (aarch64), so without following instructions to use Rosetta2 x86 emulation.
A workaround until pyenchant is fixed is to run
export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib in the terminal session before you execute
Available documentation builds#
All build and check documentation commands use the file
To see the most frequently used builds, use the following command.
Else you can open
Makefile to see other build formats, including PDF.
html is the HTML version of the documentation.
/_build/html/index.html in a web browser.
livehtml rebuilds Sphinx documentation on changes, with live-reload in the browser.
Open http://0.0.0.0:8000/ in a web browser.
spellcheck checks the spelling of words.
See American English Spelling, Grammar, and Syntax for configuration.
/_build/spellcheck/ for misspellings.