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 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-validatorputs content in the same directories as the website.write/matches literal string, only matching paths that containwrite/..*matches zero or more additional characters, matching all pages under thewrite/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 containdevelopers/plugins/.*matches zero or more additional characters, matching all pages under thedevelopers/plugins/directory.$matches the empty string at the end of a line, anchoring the regular expression to the end of the input.
Last reviewed: May 23, 2024
