Automated validation with doc-validator

Every project keeps technical documentation in the docs/sources directory. 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 from the docs/ directory. 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. See also `docs-no-pull`.
  docs-no-pull     Serve documentation locally without pulling the `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image.
  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.
  vale             Run vale on the entire docs folder.
  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 file 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.