记录 ROS 2 包

本指南介绍了为 ROS 2 软件包创建文档的标准方法。 对于具有二进制版本的软件包，这还会导致文档托管在“docs.ros.org/en/<distro>/p/<package>/”上。 有关如何在 docs.ros.org 上为该文档做出贡献的信息，请参阅：doc：为 ROS 2 文档做出贡献 <../The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation>”。

先决条件

软件包文档概述

本指南中讨论的文档类型称为“软件包文档”或“API 文档”。

对于已在 ROS Index 上发布的 ROS 软件包，其文档将在 ROS buildfarm 上构建，包含在 docs.ros.org 上，并可通过 index.ros.org 上的“API 文档”按钮查看。

负责生成 ROS 2 软件包文档的工具是“rosdoc2 <https://github.com/ros-infrastructure/rosdoc2>”__。

“rosdoc2”是常用的“Sphinx <https://www.sphinx-doc.org/>”__文档框架的便捷包装器。 Sphinx 允许自由格式的书面文档以及从代码中的注释生成的 Python 代码的 API 文档。 breathe + exhale 包允许与 Doxygen 集成，包括自动生成的 C++ API 文档。

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

构建包文档

要使用 rosdoc2 以 HTML 格式生成包文档，请运行：

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

文档写入 docs_output/<package-name>/index.html，可在浏览器中查看。

配置

ROS 包文档有三个配置位置：rosdoc2.yaml 用于常规设置， conf.py 用于 sphinx 设置，Doxyfile 用于 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 readme <https://github.com/ros-infrastructure/rosdoc2#using-a-rosdoc2yaml-file-to-control-how-your-package-is-documented>”__。

conf.py，rosdoc2_settings

包文档的最终输出（几乎）总是由 Sphinx 构建。 每个 Sphinx 项目都由“doc”目录中的“conf.py”文件配置。 如果不存在配置，则会在构建文档时创建并使用默认的 Sphinx 项目。 但是，如果在包的“doc”子目录中找到“conf.py”Sphinx 配置，则使用它。 如果要包含独立的 reStructuredText 文档页面，则需要自定义 Sphinx 项目。 独立文档页面可用于列出多个教程和指南；如果您希望在包中使用它们，则需要创建自定义 Sphinx 项目。

“rosdoc2”为“conf.py”提供附加设置并覆盖一些设置。 有关对 Sphinx 设置所做的更改的信息将以“[rosdoc2]”前缀记录到控制台。

Doxyfile

Doxygen 是一种从代码注释自动生成 C++ API 文档的工具。 虽然 Doxygen 也可以直接生成 HTML 输出，但在 ROS 包的通常工作流程中，Doxygen 会生成机器可读的 XML 格式的输出，然后由 Sphinx 使用并与其余文档集成。 仅通过在“rosdoc2.yaml”中启用 Doxygen 构建器即可生成仅 Doxygen 文档，但这种情况并不常见。

自定义 Sphinx 文档

创建 Sphinx 项目

为了在自动生成的 API 文档之外添加独立文档页面，需要自定义 Sphinx 项目。 应在包目录中名为“doc”的子目录中创建此项目。 可以通过在“doc”目录中运行“sphinx-quickstart”来创建新的 Sphinx 项目，对“分离源和构建目录”回答“否”。 向导要求输入项目名称、作者和版本，但稍后可以删除这些信息，并由“rosdoc2”从包“package.xml”中提供给 Sphinx。 有关创建 sphinx 项目的更多信息，请参阅 Sphinx 快速入门页面,

自定义 index.rst

sphinx-quickstart 向导会创建一个 index.rst 文件，它是您的包的自定义登录页面，类似于 Github README 文件。

添加 Python API 文档

默认情况下，“rosdoc2”使用“sphinx-apidoc 工具 <https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html>”和“autodoc Sphinx 扩展 <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>”自动生成 Python 代码文档。 为了让 autodoc 找到包中的 Python 模块，必须将其添加到“conf.py”中的 Python 搜索路径中：

sys.path.insert(0, os.path.abspath('.'))

这是因为“rosdoc2”用来自将放置在包中的脚本的更多配置包装了自定义“conf.py”。 在这种情况下，“os.path.abspath”中的“。”路径指的是包的目录根目录，而不是包的“doc”目录，这是由于 rosdoc2 和“conf.py”之间的交互。 默认情况下，包 API 文档已经可以通过登录页面上的“模块索引”链接访问。 要使 API 文档也出现在目录中，只需将“modules”页面的链接添加到“index.rst”即可：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   Python Modules <modules>

添加 C++ API 文档

如果您想要将自动生成的 API 文档添加回自定义登录页面，请将行“generated/index”添加到您希望 API 文档出现的文档页面：

.. toctree::
   :maxdepth: 2

   C++ API Docs <generated/index>

这会将元素“类层次结构”、“文件层次结构”和“参考”添加到侧边栏的目录中。 为了使这些元素出现在一个“C++ API 文档”标题下，以使侧边栏不那么混乱，可以添加一个单独的文件，例如“cpp_api_docs.rst”，它链接到生成的文档：

cpp_api_docs.rst
C++ API Docs
============

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

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   generated/index

然后还需要将其添加到“index.rst”中以显示在侧边栏中：

index.rst
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   cpp_api_docs

包含现有的 README.md

如果您的 git 存储库已经有现有的 README.md，则可以将其重新用作文档的登录页面，而无需重复内容。

要在 Sphinx 中正确包含 Markdown 文件，同时保留相对链接和图像，需要做一些额外的工作。

首先，在 index.rst 旁边创建一个代理文件 readme_include.md。 这是一个 markdown 文件，它只包含原始 README.md，但保留了相对图像路径，否则在下一步中会中断：

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

然后，从“index.rst”包含此文件的内容，使用“myst”从 rst 包含 markdown：

index.rst
.. include:: readme_include.md
   :parser: myst_parser.sphinx_

这还需要在“conf.py”中的扩展中添加“myst_parser”：

conf.py
extensions = ["myst_parser"]

CI，docs.ros.org

ROS 构建农场使用“rosdoc2”来构建托管在“docs.ros.org/en/<distro>/p/<package>/”上的软件包文档。 要启用此功能，必须在“rosdistro/rolling/distribution.yaml <https://github.com/ros/rosdistro/blob/master/rolling/distribution.yaml>”中配置包含文档的存储库。 这通常是软件包源存储库：

<package_name>:
  doc:
    type: git
    url: https://github.com/<github_username>/<package_name>.git
    version: main
  release:
  [...]

buildfarm 单独托管每个发行版的文档，并定期从指定分支上的最新提交重建它。 无需标记新版本即可更新托管的文档。 要查看软件包文档构建的状态，请在 https://build.ros2.org 上搜索 doc__<package_name>。 为软件包发布的每个发行版创建一个作业。 在每个作业页面上，您可以看到上次触发构建的时间，以及每次构建的状态和日志。

进一步阅读