自动文档检查

命令行工具 doc-checker 会对文档源代码执行多项检查。将更改提交到 //docs 目录时，不需要访问外部链接的检查将作为提交前检查执行。

文档检查工具的主要目标是确保 //docs 目录中的所有文档属于由 _toc.yaml 文件和页内链接构成的互连图的一部分，当文档发布在 fuchsia.dev 上时，这些文档可以访问。其他检查会检查链接本身，以强制执行文档标准和一致性。

运行文档检查工具

fx doc-checker

添加 --local-links-only 即可跳过外部链接检查。

如需了解更多选项，请参阅完整的命令行参考。

如果由于某种原因它不属于当前的 build 配置，请重新运行 fx set，并添加用于构建 doc_checker 的选项：--with //tools/doc_checker:doc_checker。

以下是文档检查工具报告的情况：

[missing doc](/docs/does_not_exist.md)

这些是引用 fuchsia.googlesource.com 或 fuchsia.dev 并访问 //docs 中的文件的链接。这些链接应转换为文件路径。

不正确

[unnessary link](https://fuchsia.dev/fuchsia-src/get-started/learn-fuchsia.md)

正确

[correct link](/docs/get-started/learn-fuchsia.md)

这些项目包含在 Fuchsia 源代码树中，已合并到 Fuchsia 或已完成弃用。有效项目列表是源代码的一部分。


     [invalid old project](https://fuchsia.googlesource.com/garnet/+/refs/heads/main)

这些链接指向 //docs 目录之外的路径。这些路径应转换为 fuchsia 相对路径。

不正确

  [source file](/docs/../src/BUILD.gn)

正确

   [source file](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/BUILD.gn)

图片中缺少alt文字

图片必须包含有意义的 alt 文本。

![Diagram of the state transitions](/docs/state-machine.png "State machine")

包含 Markdown fragment 文件

Markdown 文件片段包含在另一个 Markdown 文件中，具体方法是使用

<<relative-path-to/_file.md>>

该路径必须相对于当前的 .md 源文件，不能使用绝对路径。<< >> 指令是一个块指令，因此必须单独占用一行。

YAML 数据文件检查

fuchsia.dev 中的 YAML 文件用于以结构化格式存储文档内容，然后使用 Jinja 模板呈现这些内容。任何以 _ 为前缀的 YAML 文件都表示 YAML 未作为独立文件发布，而是仅通过使用模板进行呈现。如果 YAML 文件不带 _ 前缀，则该 YAML 文件会发布在 fuchsia.dev 上，并且可以作为普通 YAML 文件查看。

_toc.yaml 检查

_toc.yaml 文件主要用于创建 fuchsia.dev 的信息架构。

这些检查将强制执行 _toc.yaml 参考文档中所述的目录结构。

  • 顶级键 toc

  • 条目可以是以下其中一项：

    • break: true -（可选）添加垂直分页符
    • contents: <list of toc entries> -（可选）自定义标签的内容。
    • heading: <string> -（可选）一组链接的标题。
    • include: <path to _toc.yaml> -（可选）包含另一个 _toc.yaml。
    • name: <string> -（可选）此标签页的名称。
    • path: <string> -（可选）网页路径或网址。
    • path_attributes: <mapping> -（可选）为基于 path 属性创建的链接的属性名称-值对。
    • section: <toc entry> -（可选）用于定义可收起部分的缩进 toc 条目，通常通过 include 定义另一个 _toc.yaml 文件。
    • skip_translation: true -（可选）防止对此条目以及任何后代中的所有链接标题进行人工翻译和机器翻译。
    • status: <string> -（可选）与 heading 或 title 一起使用，不能与 break 或 include 一起使用。应用预定义的状态。该状态必须是以下状态之一：
    • alpha
    • beta
    • deprecated
    • experimental
    • external
    • limited
    • new
    • step_group: <string> -（可选）用于创建内容组，其中包含指向页面底部的 prev 和 next 导航链接。
    • style: <string> -（可选）不能与 break 或 include 一起使用。此样式已应用于 heading 或 section 元素。此值必须为 accordion。
    • title: string -（可选）链接标题。

  • path 属性是有效路径：

    • 文件路径，例如 /docs/somewhere/file.md
    • http:// 或 https:// 网址。
    • /reference 来访问生成的参考文档。系统会使用指向 fuchsia.dev/reference 的外部链接来验证这些链接。
    • 特殊文件：/CONTRIBUTING.md 和 /CODE_OF_CONDUCT.md。

_toc.yaml 图表中未引用的网页

//docs 中的 Markdown 页面必须显示在 _toc.yaml 中，该目录包含在从 //docs/_toc.yaml 中的根 _toc.yaml 创建的目录中。

_areas.yaml 的结构

待定：areas.yaml__ 的结构是什么？

_eng_council.yaml 的结构

待定：_eng_council.yaml?

_metadata.yaml 的结构

待定：metadata.yaml 的用途是什么？

_rfcs.yaml 的结构

此文件用于定义 RFC 文档的元数据。

请参阅 RFC 元数据。

_roadmap.yaml 的结构

待定：roadmap.yaml 的用途是什么？

_drivers_areas.yaml 的结构

待定：_drivers_areas.yaml?

_drivers_epitaphs.yaml 的结构

待定：__driversepitaphs.yaml 的用途是什么？

_problems.yaml 的结构

待定：problems.yaml 的用途是什么？

_redirects.yaml 的结构

此文件定义给定网址指向另一个网页的重定向。

_supported_cpu_architecture.yaml 的结构

待定：_supported_cpu_architecture.yaml?

_supported_sys_config.yaml 的结构

支持的系统配置列表。

请参阅支持的系统配置列表

_tools.yaml 的结构

待定：tools.yaml 有什么用途？

请参阅：源代码

_已弃用-docs.yaml 的结构

此文件定义了已弃用的文档的重定向规则。

请参阅：将网页重定向至弃用通知。

_glossary.yaml 的结构

此文件定义了 Fuchsia 术语的术语表。

请参阅：添加术语表术语

    [broken link](https://mispeeled.com)

针对 Google 托管的网站添加 hl 参数

hl 参数指示用户的主语言。该参数不应包含在网址中，因为它会停用自动重定向到已翻译的网页（如果存在）的功能。