Building and checking the quality of documentation#

This document covers how to set up and build the Plone Documentation and check it for quality.

Installation#

Installation of Plone 6 Documentation includes pre-requisites and the repository itself.

  • An operating system that runs all the requirements mentioned. Most UNIX-based operating systems are supported, including many Linux distributions, macOS, or Windows Subsystem for Linux (WSL) on Windows. A UNIX-based operating system is recommended.

    Important

    Windows alone is not recommended because it does not support GNU make. If you get Plone to run on Windows alone, please feel free to document and share your process.

Python#

Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, pyenv that allows you to install multiple versions of Python on your development environment without destroying your system's Python. Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.

GNU make#

Make comes installed on most Linux distributions. On macOS, you must first install Xcode, then install its command line tools. On Windows, it is strongly recommended to Install Linux on Windows with WSL, which will include make.

Finally, it is a good idea to update your system's version of make, because some distributions, especially macOS, have an outdated version. Use your favorite search engine or trusted online resource for how to update make.

Graphviz#

Install Graphviz for graph visualization.

brew install graphviz

sudo apt-get install graphviz

Clone plone/documentation#

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.

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