菜单
文档面包屑箭头 Writers' Toolkit面包屑箭头 构建和审阅面包屑箭头 测试文档更改
开源
最后审阅时间：2024 年 5 月 28 日

测试文档更改

每个项目的技术文档都保存在 docs/sources 目录中，并发布到网站仓库的 content/docs 目录中。

此外，每个项目都使用 GNU Make 执行与技术文档相关的任务。要了解更多关于 GNU Make 的信息，请参考 GNU Make 手册。

要查看目标列表及其说明，请在 docs/ 目录中运行 make help。如果您在网站仓库中，请改为在仓库根目录中运行 make help。

输出如下所示：

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

要运行本地文档 Web 服务器，请在 docs/ 目录中运行 make docs。如果您在网站仓库中，请改为在仓库根目录中运行 make docs。

注意

在错误的目录中运行 make docs 会产生输出 make: Nothing to be done for 'docs'. 或 make: *** No rule to make target 'docs'. Stop.，并且不会启动本地文档 Web 服务器。要运行本地文档 Web 服务器，请确保您位于正确的目录中。

成功构建的输出消息包含一个 URL，您可以按照该 URL 在浏览器中查看文档更改。请参考成功构建示例。

运行特定项目

运行 make docs 时，每个仓库默认构建的项目列表由 docs/variables.mk 中的 PROJECTS 变量定义。要覆盖默认设置，请向 make docs 提供 PROJECTS 选项。该参数是一个由项目名称组成的空格分隔列表。

仓库的项目名称是网站 /docs/ 目录下该仓库发布文档的子目录。例如：

  • 对于 Grafana，PROJECT 是 grafana，源自 URL https://grafana.org.cn/docs/grafana/。
  • 对于 Grafana Cloud，PROJECT 是 grafana-cloud，源自 URL https://grafana.org.cn/docs/grafana-cloud/。

注意

对于在 PROJECTS 的空格分隔列表中指定的任何项目，您必须在本地克隆了相应的仓库，命令才能成功执行。

仅构建 Grafana 文档

bash 
make docs PROJECTS=grafana

构建 Grafana 和 Grafana Cloud 文档

bash 
make docs 'PROJECTS=grafana grafana-cloud'

如果您的本地仓库名称与上游仓库名称不匹配。您可以使用 PROJECTS 选项来覆盖目录。

例如，如果您将 Tempo 仓库 tempo 克隆到一个名为 tempo-doc-work 的目录中。

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

格式为 <PROJECT>[:VERSION[:REPOSITORY[:DIRECTORY]]]。该示例将 PROJECT tempo 挂载到默认 VERSION（因为 VERSION 参数为空），使用 REPOSITORY tempo-doc-work 和默认文档 DIRECTORY docs/sources。此示例从本地工作目录 tempo-doc-work 构建 Tempo 文档，而不是从标准 tempo 目录构建。

理解 make docs 的 Hugo 输出

运行 make docs 时，Hugo 会渲染 Markdown 文件并输出警告和错误消息。

Hugo output for running make docs

这些消息采用以下格式：

text 
<LEVEL> [LANGUAGE] <MESSAGE>

其中

  • <LEVEL> 是 WARN 或 ERROR 之一
  • 可能存在 <LANGUAGE>
  • <MESSAGE> 是问题描述

示例：成功构建

如果 make docs 命令运行正确，控制台会打印类似于以下消息：

View documentation locally:
  https://:3002/docs/grafana/latest/

Press Ctrl+C to stop the server

注意

要测试 Grafana 教程更改，地址为 https://:3002/docs/grafana/latest/tutorials/。

示例：页面未找到

构建文档时，Hugo 会发出 REF_NOT_FOUND 警告，指示此类引用的文件名和位置，例如在 grafana/grafana 中使用 make docs 或在 grafana/website 中使用 make server-quick 时

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

在此示例中，

  • Ref "../../enterprise" 是 Hugo 无法解析的引用的目标地址
  • \/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md 是包含该引用的文档，其中 /next/ 之后的路径相对于组件仓库的文档根目录
  • :14 表示包含未解析引用的行号
  • :47 表示该行中未解析引用开始的字符位置

如果看到此错误，则引用的目标无效。这可能是由于引用中的拼写错误或目标目录路径不正确造成的。通过更正引用目标来修复错误。

有关链接的更多信息，请参考链接。

示例：由于缺少短代码而重建失败

在此示例中，重建失败，因为文件 contribute-documentation/_index.md 在第 152 行缺少 admonition 的关闭短代码。

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

扩展用法

请参考以下部分，了解 make docs 更复杂的用法示例。

将文档挂载到其他版本

make docs PROJECTS=grafana:next

同时挂载 v9.3.x 和默认版本的 Grafana 文档

从仓库根目录运行以下命令，添加包含 v9.3.x 分支的工作树

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

切换到 docs/ 目录

bash 
cd docs

使用两个版本运行 make docs

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

要移除工作树，请从仓库根目录运行以下命令

bash 
git worktree remove v9.3.x

参数

make-docs 脚本的每个参数都是一个要挂载到本地构建的项目。每个参数有四个字段，用冒号（:）分隔，可选字段可以省略。

<PROJECT>[:VERSION[:REPOSITORY[:DIRECTORY]]]

  • <PROJECT>：是网站 /docs/ 目录下仓库发布文档的子目录。

    例如：

    • 对于 Grafana，<PROJECT> 是 grafana (https://grafana.org.cn/docs/grafana/)
    • 对于 Grafana Cloud，<PROJECT> 是 grafana-cloud (https://grafana.org.cn/docs/grafana-cloud/)。

    伪项目（Pseudo projects）挂载多个源目录。

    • logs：挂载 Loki 和 Grafana Enterprise Logs (GEL) 目录。
    • metrics：挂载 Mimir、mimir-distributed Helm Chart 和 Grafana Enterprise Metrics (GEM) 目录。
    • traces：挂载 Tempo 和 Grafana Enterprise Traces (GET) 目录。

    注意

    伪项目（Pseudo projects）不支持 <REPOSITORY> 或 <DIR> 字段。

  • <VERSION>：是用于挂载文档的版本目录名称。

    <VERSION> 字段是可选的，对于有版本控制的项目，默认为 latest，对于其他项目为空。

  • <REPOSITORY>：是克隆项目所在的目录名称。

    <REPOSITORY> 字段是可选的，默认为脚本内部的项目名称到仓库名称的映射。对于大多数项目，这与项目名称相同。

  • <DIRECTORY>：是仓库内包含技术文档的目录路径。

    <DIRECTORY> 字段是可选的，默认为脚本内部的项目名称到文档源目录的映射。对于大多数项目，它是 docs/sources 目录。

REPOS_PATH

REPOS_PATH 环境变量是一个由冒号分隔的路径列表，用于查找项目仓库。脚本只会在 REPOS_PATH 中指定的目录中检查项目。

默认情况下，脚本会将 REPOS_PATH 确定为当前项目的父目录。如果您将所有仓库都保存在同一目录中，则无需设置 REPOS_PATH。

目录结构类似于从 tree -L 1 -d ~/ext/grafana 命令获得的以下输出

console 
/home/username/ext/grafana
├── agent
├── grafana
├── loki
├── mimir
├── phlare
├── technical-documentation
├── tempo
├── website
└── writers-toolkit

9 directories

当您从 Grafana 仓库运行 make docs 时，脚本会将 REPOS_PATH 设置为 /home/username/ext/grafana。

DEBUG

DEBUG 环境变量会禁用输出过滤并启用额外的调试日志，以帮助进行故障排除。

如果您在使用 make docs 过程时遇到令人困惑的行为，请通过 GitHub Issue 或（如果您是 Grafana Labs 员工）在 #docs Slack 频道报告问题，并提供使用 make docs DEBUG=true 命令的完整命令和输出。

停止运行本地构建

要停止 make docs 命令，请按 Command/Ctrl + C。

有时旧的构建过程可能正在另一个终端中运行。如果是这种情况，当您运行 make docs 时，您会看到类似于以下的输出

console 
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

要移除旧的构建过程，请执行以下操作之一：

  • 打开 Docker Desktop，转到 容器，并停止所有运行的容器或仅停止您本地构建的容器。
  • 要移除所有运行的容器，请运行 docker rm -f $(docker ps -q)。