Automated validation with doc-validator

Every project keeps technical documentation that’s published to the website in the docs/sources directory. That documentation is published to the content/docs directory in the website repository.

Additionally, every project uses GNU Make to perform tasks related to technical documentation. To learn more about GNU Make, refer to GNU Make Manual.

To see a list of targets and their descriptions, run make help from the docs/ directory. If you are in the website repository, run make help from the root of the repository instead.

The output is similar to the following:

Usage:
  make <target>

Targets:
  help             Display this help.
  docs-rm          Remove the docs container.
  docs-pull        Pull documentation base image.
  make-docs        Fetch the latest make-docs script.
  docs             Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. To not pull the image, set `PULL=false`.
  docs-debug       Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
  doc-validator    Run doc-validator on the entire docs folder which includes pulling the latest `DOC_VALIDATOR_IMAGE` (default: `grafana/doc-validator:latest`) container image. To not pull the image, set `PULL=false`.
  vale             Run vale on the entire docs folder which includes pulling the latest `VALE_IMAGE` (default: `grafana/vale:latest`) container image. To not pull the image, set `PULL=false`.
  update           Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.

To validate technical documentation with doc-validator, run make doc-validator from the docs/ directory.

Error codes

All errors include an error code. You can find documentation for each error code in Errata for doc-validator.

Run on specific files

The script that invokes doc-validator mounts projects using the Hugo website structure. All projects are subdirectories of /hugo/content/docs/.

To run doc-validator on specific files, provide the <DOC_VALIDATOR_INCLUDE> argument to your make command. It’s value is a regular expression that the tool matches against paths. doc-validator only lints the paths that the regular expression matches.

Example

When in the Writers’ Toolkit repository, to only validate content in the /docs/sources/write/ directory, run the following command:

make doc-validator DOC_VALIDATOR_INCLUDE='^/hugo/content/docs/writers-toolkit/write/.*$'

Explanation of the regular expression

^ matches the empty string at the beginning of a line, anchoring the regular expression to the start of the input.
Writers’ Toolkit isn’t a versioned project and its documentation is synced directly into the /hugo/content/docs/writers-toolkit/ directory in the website repository.
make doc-validator puts content in the same directories as the website.
write/ matches literal string, only matching paths that contain write/.
.* matches zero or more additional characters, matching all pages under the write/ directory.
$ matches the empty string at the end of a line, effectively anchoring the regular expression to the end of the input.

Grafana repository, `/docs/sources/developers/plugins/` directory

When in the Grafana repository, to only validate content in the /docs/sources/developers/plugins/ directory, run the following command:

make doc-validator DOC_VALIDATOR_INCLUDE='^/hugo/content/docs/grafana/latest/developers/plugins.*$'

Explanation of the regular expression

^ matches the empty string at the beginning of a line, anchoring the regular expression to the start of the input.
Grafana is a versioned project. By default the script puts Grafana content into the /hugo/content/docs/grafana/latest/ directory.
developers/plugins/ matches the literal string, only matching paths that contain developers/plugins/
.* matches zero or more additional characters, matching all pages under the developers/plugins/ directory.
$ matches the empty string at the end of a line, anchoring the regular expression to the end of the input.