Test documentation changes
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 docs-validator on the entire docs folder.
doc-validator/% Run doc-validator on a specific path. To lint the path /docs/sources/administration, run 'make doc-validator/administration'.
docs.mk Fetch the latest version of this Makefile from Writers' Toolkit.
To run the local documentation webserver with the default configuration, run make docs
from the docs/
directory.
Run with specific projects
Each project has a list of projects to build by default when running make docs
that is defined by the PROJECTS
variable in docs/variables.mk
.
To override the default for a single invocation, provide the PROJECTS
argument to make docs
which is the name of the project as it appears in the website URL path.
For example:
- For Grafana, the
PROJECT
isgrafana
derived the URLhttps://grafana.com/docs/grafana/
. - For Grafana Cloud, the
PROJECT
isgrafana-cloud
derived from the URLhttps://grafana.com/docs/grafana-cloud/
.
Note: You must have the repository cloned locally for any projects specified in the space separated list to PROJECTS
for the command to succeed.
To specifically build only the Grafana documentation:
make docs PROJECTS='grafana'
To specifically build Grafana and Grafana Cloud documentation:
make docs PROJECTS='grafana grafana-cloud'
Let’s say that you have forked the main project repository, so your local working directory name doesn’t match the project name.
You can use the PROJECTS
option to define the local cloned repository (see the Arguments section below).
make docs PROJECTS="tempo::tempo-doc-work"
The format is <PROJECT>[:VERSION[:REPOSITORY[:DIR]]].
The example mounts the PROJECT
tempo, at the default VERSION
latest, using the REPOSITORY
tempo-doc-work
, and the default DIR
docs/sources
.
This example builds the Tempo documentation from the local working directory, tempo-doc-work
, instead of the standard tempo
directory.
Understand Hugo output from make docs
When you run make docs
, Hugo (our static site generator) processes the Markdown files and outputs warnings and error messages.
These messages are in the following format:
WARN <DATE> <TIME> <LANGUAGE> REF_NOT_FOUND: Ref <RELREF ARGUMENT>: “<SOURCE FILE>:<LINE>:<COLUMN>”: <ERROR>
where:
SOURCE FILE
is the file with the brokenrelref
RELREF ARGUMENT
is the argument to therelref
shortcode that is not working.ERROR
is the reasonRELREF ARGUMENT
is not working.
When you save a file with an active local build, the page is rechecked. If the error messages is not repeated, then the issue is fixed.
Example: Page not found
Hugo emits REF_NOT_FOUND
warnings indicating the filename and location of such references when building the docs, for example with make docs
in grafana/grafana
or make server-quick
in grafana/website
:
WARN 2022/08/04 21:35:37 [en] REF_NOT_FOUND: Ref "../../enterprise": "/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md:14:47": page not found
In this example,
Ref "../../enterprise"
is the destination of the reference that Hugo can’t resolve\/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md
is the document containing the reference, where the path after/next/
is relative to the documentation root of the component repository:14
represents the line number containing the unresolved reference:47
represents the character in that line where the unresolved reference begins
If the reference’s destination appears to be invalid, for example due to a typo in the reference or the depth of therelref
directory, then you should be able to resolve this by correcting the reference target.
For more information about linking, refer to Links and cross references.
Example: Rebuild failed due to missing shortcode
In this example, the rebuild fails because the file contribute-documentation/_index.md
is missing a closing shortcode for admonition
on line 152.
ERROR Rebuild failed: assemble: "/hugo/content/docs/writers-toolkit/contribute-documentation/_index.md:152:1": failed to extract shortcode: shortcode "admonition" must be closed or self-closed
Reference
The make docs
target uses the make-docs
script to mount local documentation into the Hugo build.
It can also be run separately if special configuration is required.
Examples
The following examples assume:
- Your working directory is the root of a project repository.
- You have a copy of the
make-docs
script in that working directory. - The script is executable.
- You have a checkout of each of the project repositories used in the examples.
Build Mimir, the mimir-distributed
Helm chart, and GEM: ./make-docs metrics
Build Loki and GEL: ./make-docs logs
Build Tempo and GET: ./make-docs traces
Build Grafana and Grafana Cloud: ./make-docs grafana grafana-cloud
Build Grafana and Mimir as “next”: ./make-docs grafana:next mimir:next
Mount v9.3.x
and “latest” versions of Grafana::
From the grafana
repository:
$ git worktree add v9.3.x origin/v9.3.x
$ export GRAFANA_REPO="$(pwd)"
From the technical-documentation
repository:
$ ./make-docs grafana "grafana:v9.3.x:${GRAFANA_REPO}/v9.3.x"
To remove the worktree created in the grafana
repository, run the following command from the grafana
repository:
$ git worktree remove v9.3.x
Arguments
Each argument to the make-docs
script is a project to be mounted into the local build.
Each argument has four fields separated by colons (:
) and optional fields can be omitted.
<PROJECT>[:VERSION[:REPOSITORY[:DIR]]]
PROJECT
: is the name of the project as it appears in the website URL path.For Grafana, the
PROJECT
isgrafana
(https://grafana.com/docs/grafana/
) For Grafana Cloud, thePROJECT
isgrafana-cloud
(https://grafana.com/docs/grafana-cloud/
).Pseudo projects mount multiple source directories.
logs
: mounts Loki and GEL directories.metrics
: mounts Mimir, themimir-distributed
Helm chart, and GEM directories.traces
: mounts Tempo and GET directories.
Note: pseudo projects do not support the
REPOSITORY
orDIR
fields.VERSION
: is the name of the version directory under which the project documentation should be mounted.The
VERSION
field is optional and defaults tolatest
for versioned projects and is empty for other projects.REPOSITORY
is the the name of the local directory withinREPOS_PATH
for that project.The
REPOSITORY
field is optional and defaults to the scripts internal mapping of project names to repository names. For most projects, this is the same as the project name.The
DIR
field is the directory path within the repository that is where the source documentation resides.The
DIR
field is optional and defaults to the scripts internal mapping of project names to documentation source directories. For most projects, this is thedocs/sources
directory.
This example builds the Grafana documentation and the Tempo documentation from the local repository, tempo-doc-work
.
make docs PROJECTS="grafana tempo::tempo-doc-work"
REPOS_PATH
The REPOS_PATH
environment variable is a colon-separated list of paths in which to look for project repositories.
Only directories within the paths specified in REPOS_PATH
are checked for projects.
By default, the script determines the REPOS_PATH
to be the parent directory of the grafana/technical-documentation
repository.
If you keep all repositories in the same directory, you do not need to set REPOS_PATH
.
With a directory structure similar to the following tree
command:
$ tree -L 1 -d ~/ext/grafana
/home/jdb/ext/grafana
├── agent
├── grafana
├── loki
├── mimir
├── phlare
├── technical-documentation
├── tempo
├── website
└── writers-toolkit
9 directories
The script sets REPOS_PATH
to be /home/jdb/ext/grafana
.
DEBUG
The DEBUG
environment variable disables output filtering and enables extra debug logging to help with troubleshooting.
If you experience confusing behavior with the make docs
procedure, report the problem via a GitHub issue or, for Grafana Labs employees, in the #docs Slack channel and provide the full command and output using make docs DEBUG=true
.
Stop running a local build
To stop the make docs
command, press Commmand/Ctrl + C.
If this doesn’t work, do one of the following:
- (Recommended) Open Docker Desktop, go to Containers, and stop all running containers or just the one for your local build.
- To remove all running containers, run
docker rm -f $(docker ps -q)
.