DocumentationWriters' ToolkitBuild and reviewTest documentation changes

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:

console Copy

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 run the local documentation web server, run make docs from the docs/ directory.

Run with specific projects

Each repository has a list of projects to build by default when running make docs, defined by the PROJECTS variable in docs/variables.mk. To override the defaults, provide the PROJECTS option to make docs. The argument is a space-separated list of names of the projects.

The project name for a repository is the sub-directory of the /docs/ directory in the website where the repository publishes documentation. For example:

• For Grafana, the PROJECT is grafana derived the URL https://grafana.com/docs/grafana/.
• For Grafana Cloud, the PROJECT is grafana-cloud derived from the URL https://grafana.com/docs/grafana-cloud/.

To build only the Grafana documentation:

bash Copy

make docs PROJECTS='grafana'

To build Grafana and Grafana Cloud documentation:

bash Copy

make docs PROJECTS='grafana grafana-cloud'

If your local repository name doesn’t match the upstream repository name. You can use the PROJECTS option to override the directory.

For example, if you have the Tempo repository tempo cloned into a directory called tempo-doc-work.

bash Copy

make docs PROJECTS="tempo::tempo-doc-work"

The format is <PROJECT>[:VERSION[:REPOSITORY[:DIRECTORY]]]. The example mounts the PROJECT tempo, at the default VERSION (since the VERSION is left empty), using the REPOSITORY tempo-doc-work, and the default documentation DIRECTORY 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 renders the Markdown files and outputs warnings and error messages.

These messages are in the following format:

text Copy

<LEVEL> [LANGUAGE] <MESSAGE>

where:

• LEVEL is one of WARN or ERROR
• LANGUAGE may be present
• MESSAGE is the issue

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:

Copy

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.

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.

Copy

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

Extended usage

Refer to the following sections for examples of more complicated usage of make docs.

Mount documentation to a different version

Copy

make docs 'PROJECTS=grafana:next'

Mount v9.3.x and the default version of Grafana documentation together

Run the following command from the root of the repository to add a worktree that contains the v9.3.x branch:

bash Copy

git worktree add v9.3.x origin/v9.3.x

Change to the docs/ directory:

bash Copy

cd docs

Run make docs with both versions:

Copy

make docs 'PROJECTS=grafana grafana:v9.3.x:grafana'

To remove the worktree, run the following command from the root of the repository:

bash Copy

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[:DIRECTORY]]]

• PROJECT: is the sub-directory of the /docs/ directory in the website where the repository publishes documentation.

  For example:

  • For Grafana, PROJECT is grafana (https://grafana.com/docs/grafana/)
  • For Grafana Cloud, PROJECT is grafana-cloud (https://grafana.com/docs/grafana-cloud/).

  Pseudo projects mount multiple source directories.

  • logs: mounts Loki and Grafana Enterprise Logs (GEL) directories.
  • metrics: mounts Mimir, the mimir-distributed Helm chart, and Grafana Enterprise Metrics (GEM) directories.
  • traces: mounts Tempo and Grafana Enterprise Traces (GET) directories.

  Note

  Pseudo projects don’t support the REPOSITORY or DIR fields.

• VERSION: is the name of the version directory to mount the documentation in.

  The VERSION field is optional and defaults to latest for versioned projects and is empty for other projects.

• REPOSITORY: is the name of the directory that the project is cloned to.

  The REPOSITORY field is optional and defaults to the script’s internal mapping of project names to repository names. For most projects, this is the same as the project name.

• DIRECTORY: is the directory path within the repository containing the technical documentation documentation.

  The DIRECTORY field is optional and defaults to the script’s internal mapping of project names to documentation source directories. For most projects, it’s the docs/sources directory.

REPOS_PATH

The REPOS_PATH environment variable is a colon-separated list of paths in which to look for project repositories. The script only checks for projects in the directories specified in REPOS_PATH.

By default, the script determines the REPOS_PATH to be the parent directory of the current project. If you keep all repositories in the same directory, you don’t need to set REPOS_PATH.

With a directory structure similar to the following tree command:

console Copy

$ tree -L 1 -d ~/ext/grafana
/home/username/ext/grafana
├── agent
├── grafana
├── loki
├── mimir
├── phlare
├── technical-documentation
├── tempo
├── website
└── writers-toolkit

9 directories

When you run make docs from the Grafana repository, the script sets REPOS_PATH to be /home/username/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.

Sometimes an old build process can be running in another terminal. If this is the case, when you run make docs, you see output similar to the following:

console Copy

docker: Error response from daemon: driver failed programming external connectivity on endpoint eloquent_nightingale (eb2c4546727b41bbc44354ac616a14404c57f30c312f6869b147c578ac5de6bf): Bind for 0.0.0.0:3002 failed: port is already allocated.
make: *** [docs] Error 125

To remove an old build process, do one of the following:

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