Set up, build, and check the quality of documentation

Set up, build, and check 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 prerequisites 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 6.1 requires Python version 3.10, 3.11, 3.12, or 3.13.

Warning

Do not create or activate a Python virtual environment at this time. The instructions below will create one.

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#

In a terminal session, clone the Plone Documentation repository, and change your working directory into the cloned project. Then with a single make command, create a Python virtual environment, install project dependencies, pull in documentation from remote repositories as a git submodule, build the documentation, and preview the results in a web browser.

git clone https://github.com/plone/documentation.git
cd documentation
make livehtml

Available documentation builds#

All build and check commands use the file Makefile. To see descriptions of the builds and checks, use the following command.

make help

Else you can open the Makefile file to see other build formats.

The following sections describe the most frequently used make commands while in the primary documentation folder.

All make commands that build documentation will

  • create a Python virtual environment,

  • install requirements,

  • initialize or update the volto, plone.restapi, and plone.api submodules, and

  • finally create symlinks to the source files.

Tip

If you want to build documentation for only one of the subprojects, navigate to the root of the project in the /submodules folder, then use any of the following commands, but with the prefix of docs-.

cd submodules/volto
make docs-livehtml

livehtml#

livehtml rebuilds documentation as you edit its files, with live reload in the browser.

make livehtml

The console will give you the URL to open in a web browser. The URL may vary, according to its configuration in the repository's Makefile.

[sphinx-autobuild] Serving on http://127.0.0.1:8050

linkcheckbroken#

linkcheckbroken checks all links, returning a list of only broken links. See All links must be valid for configuration.

make linkcheckbroken

Open /_build/linkcheck/output.txt for the entire list of links that were checked and their result.

vale#

vale checks for American English spelling, grammar, syntax, and the Microsoft Developer Style Guide. See Vale for American English spelling, grammar, and syntax, and style guide for configuration.

make vale

See the output on the console for suggestions.

clean#

clean removes all builds and cached files of the documentation. Use this command before a build to troubleshoot issues with edits not showing up and to ensure that cached files do not hide errors in the documentation.

make clean

distclean#

distclean cleans the documentation build directory, Python virtual environment, and symlinks. Use this command when packages that you have installed in your virtual environment yield unexpected results.

make distclean
Contents