Building and checking the quality of documentation
Building and checking the quality of documentation#
This document covers how to build the OpenSPP Documentation and check it for quality.
Installation of OpenSPP Documentation includes pre-requisites and the repository itself.
Python 3.8 or later is required. A more recent Python is preferred. Use your system's package manager or pyenv to install an appropriate version of Python.
Vale is a linter for narrative text.
It checks spelling, English grammar, and style guides.
OpenSPP documentation uses a custom spelling dictionary, with accepted and rejected spellings in
Use your operating system's package manager to install Vale.
Vale also has integrations with various IDEs.
OpenSPP documentation uses a file located at the root of the repository,
.vale.ini, to configure Vale.
This file allows overriding rules or changing their severity.
The OpenSPP Documentation Team selected the Microsoft Writing Style Guide for its ease of use—especially for non-native English readers and writers—and attention to non-technical audiences.
More corrections to spellings and Vale's configuration are welcome by submitting a pull request. This is an easy way to become a contributor to OpenSPP.
Install Graphviz for graph visualization.
brew install graphviz
sudo apt-get install graphviz
Clone the OpenSPP 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/OpenSPP/documentation.git cd documentation make html
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.
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.
See the output on the console for suggestions.