您正在阅读的是开发版本的文档。有关最新发布的版本，请访问 Jazzy.

记录 ROS 2 软件包

本指南介绍了为 ROS 2 软件包创建文档的标准方法。对于发布二进制版本的软件包，这也会导致文档托管在 docs.ros.org/en/<distro>/p/<package>/.如需了解如何为 docs.ros.org 上的本文档做出贡献，请参阅为 ROS 2 文档做出贡献.

软件包文档概述 

本指南中讨论的文档类型被称为 "软件包文档 "或 "API 文档"。对于已经在 ROS Index 上发布的 ROS 软件包，其文档将在 ROS buildfarm 上构建，包含在 docs.ros.org 上，并通过 应用程序接口文件 按钮。

负责生成 ROS 2 软件包文档的工具是 rosdoc2.

rosdoc2 是对常用的斯芬克斯文档框架。Sphinx 允许自由编写文档，也允许根据代码中的注释生成 Python 代码的 API 文档。文档呼吸 + 吐气软件包允许与 Doxygen 集成，以包括自动生成的 C++ API 文档。

rosdoc2 为完全没有文档或配置的软件包创建默认配置，并应用选项来统一主题和与其他软件包集成。

构建软件包文档 

要为软件包生成 HTML 格式的文档，请使用 rosdoc2运行：

rosdoc2 build --package-path <package-path>；

编写文件的目的是 docs_output/<package-name>/index.html 并可在浏览器中查看。

配置 

ROS 软件包文档有三个配置位置： rosdoc2.yaml 进行常规设置、 conf.py 设置和 文件 用于 doxygen 设置。对于所有这些设置，如果不存在，则会假定或生成默认设置，因此它们都不是严格要求的。不过，一旦要使用自定义文本文档页面等功能，可能需要创建和修改这些设置。

rosdoc2.yaml 

这是 rosdoc2 的主要入口点。它指定了通用设置，可用于控制特定构建器（Doxygen 和 Sphinx）的执行，并决定运行哪些构建器。

rosdoc2 提供了大量配置选项，可在配置文件中进行调整 rosdoc2.yaml.要生成默认 rosdoc2.yaml 然后，您可以对其进行进一步定制，并运行：

rosdoc2 default_config --package-path <package-path>；

并添加 <rosdoc2>rosdoc2.yaml</rosdoc2>； 到您的 package.xml:

<package>；
    <!-- [...] -->；
    <export>；
        <!-- [...] -->；
        <rosdoc2>；rosdoc2.yaml</rosdoc2>；
    </export>；
</package>；

不过，对于大多数软件包来说，默认设置是 rosdoc2 就足够了，无需自定义配置。更多信息 rosdoc2.yaml 可以在 rosdoc2 自述文件.

软件包文档的最终输出（几乎）总是由 Sphinx 构建的。每个 Sphinx 项目都由一个 conf.py 文件中的 文件 目录。如果没有配置，则会创建一个默认的 Sphinx 项目，并在构建文档时使用。但如果有 conf.py Sphinx 配置在 文件 子目录，则使用此项目。如果要包含独立的 reStructuredText 文档页面，则需要自定义 Sphinx 项目。独立的文档页面可用于列出多个教程和指南；如果你想在软件包中加入这些内容，则需要创建一个自定义 Sphinx 项目。

rosdoc2 提供更多设置，以 conf.py 并覆盖某些设置。对 Sphinx 设置所做更改的信息会以 [rosdoc2] 前缀

文件 

Doxygen 是一种通过代码注释自动生成 C++ API 文档的工具。虽然 Doxygen 也能直接生成 HTML 输出，但在 ROS 软件包的通常工作流程中，Doxygen 会生成 XML 格式的机器可读输出，然后由 Sphinx 使用，并与文档的其他部分整合在一起。只需在以下选项中启用 Doxygen 生成器，即可生成纯 Doxygen 文档 rosdoc2.yaml但这种情况并不常见。

定制 Sphinx 文档 

创建斯芬克斯项目 

为了在自动生成的 API 文档之外添加独立的文档页面，有必要创建一个自定义的 Sphinx 项目。应在名为 文件 在软件包目录中。新的 Sphinx 项目可通过运行 sphinx-quickstart 在 文件 目录，应答 没有 改为 "分离源代码和编译目录"。向导要求输入项目名称、作者和版本，但随后可以删除这些信息，并通过以下方式提供给 Sphinx rosdoc2 从您的包裹 package.xml.有关创建 sphinx 项目的更多信息，请访问 Sphinx 快速入门页面,

定制 `index.rst`

"(《世界人权宣言》) sphinx-quickstart 向导创建了一个 index.rst 文件，这是软件包的自定义登陆页面，类似于 Github 的 阅读说明 锉刀

添加 Python API 文档 

默认情况下 rosdoc2 使用 sphinx-apidoc 工具和 autodoc 斯芬克斯扩展来自动生成 Python 代码的文档。为了让 autodoc 找到软件包中的 Python 模块，必须在 conf.py:

系统.路.镶嵌(0, os.路.腹泻('.'))

这是因为 rosdoc2 将自定义 conf.py 更多配置的脚本，该脚本将放在软件包中。在这种情况下 . 路径 os.path.abspath 指的是软件包的根目录，而不是软件包的 文件 目录之间的交互作用。 conf.py.

默认情况下，已可通过登陆页面上的 "模块索引 "链接访问软件包 API 文档。要让 API 文档也出现在目录中，只需添加一个链接到 模块 页面到您的 index.rst:

.. 树::
   :maxdepth： 2
   标题 内容：Python 模块 <模块>；

添加 C++ 应用程序接口-文档 

如果您想将自动生成的 API 文档添加回自定义登陆页面，请添加以下行 生成/索引 到您希望 API 文档出现的文档页面：

.. 树::
   :maxdepth： 2 C++ API 文档 <生成/索引>；

这将在侧边栏的目录中添加 "类层次结构"、"文件层次结构 "和 "参考 "元素。要使这些元素显示在一个 "C++ API 文档 "标题下，以减少侧边栏的杂乱，需要一个单独的文件，如 cpp_api_docs.rst 可链接到生成的文档：

cpp_api_docs.rst

C++ 应用程序接口文档
============

这些是自动生成的内部实施文档。

.. 树::
   :maxdepth： 3
   标题 内容：生成/索引

然后还需要在 index.rst 出现在侧边栏中：

index.rst

.. 树::
   :maxdepth： 2
   标题 内容： cpp_api_docs

包含现有的 README.md 

如果您的 git 仓库中已有一个 README.md因此，可以在不重复内容的情况下将其作为文档的着陆页。要在 Sphinx 中正确包含 Markdown 文件，同时保留相对链接和图片，还需要一些额外的工作。

首先，创建代理文件 readme_include.md 邻接 index.rst.这是一个标记文件，只包含原始的 README.md，但保留了相对图像路径，否则下一步就会中断：

readme_include.md

```{include} ../README.md :relative-images：```

然后，从 index.rst 使用 神秘 的标记：

index.rst

.. 包括:: readme_include.md
   :parser： myst_parser.sphinx_

这还需要添加 myst_parser 中的扩展名 conf.py:

conf.py

扩展 = ["myst_parser"；]

CI、docs.ros.org 

ROS 构建农场使用 rosdoc2 来构建托管在 docs.ros.org/en/<distro>/p/<package>/.要启用此功能，必须在 rosdistro/rolling/distribution.yaml.这通常是软件包源代码库：

<package_name>；:
  文件:
    类型: 笨蛋
    网址: https://github.com/<github_username>/<package_name>.git
    版本: 主要
  释放:
  [...]

构建库分别托管每个发行版的文档，并定期根据指定分支上的最新提交重建文档。更新托管文档不需要标记新版本。要查看软件包的文档构建状态，请搜索 doc__<package_name>； 关于 https://build.ros2.org.每发布一个软件包，就会创建一个任务。在每个任务页面上，你可以看到上次触发构建的时间，以及每次构建的状态和日志。