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 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.