rosdoc2

用于生成ROS 2软件包文档的命令行工具。

快速入门

此工具可以从两个角度进行查看：首先是从希望为任何给定ROS 2软件包构建文档以便查看的用户的角度，其次是从需要编写文档并配置此工具在他们的软件包上如何工作的软件包维护者的角度。

构建ROS 2软件包的文档

为了生成几乎任何ROS 2软件包的文档，运行此命令，并用适当的目录替换参数

rosdoc2 build \
  --package-path ./src/path/to/my_package_name

[注意] 如果失败，请参阅 已知问题

此命令将检查您的软件包并运行基于您的软件包配置的各种文档工具

您指定的软件包目录必须包含一个包含 package.xml 文件的单个ROS 2软件包，以及可选的YAML配置文件来配置文档构建过程

输出目录中将有 index.html 文件，您可以手动打开它，或者使用以下命令

rosdoc2 open ./doc_output/index.html

有关更高级的用法，请参阅文档。

在rosdoc2开发期间，运行未安装的rosdoc2版本可能很有帮助。这可以通过在rosdoc2主目录下运行来实现（在进行初始正常安装后，确保必备条件可用）

python3 -m rosdoc2.main <options>

设置一个用于此工具的ROS 2软件包

在许多情况下，C/C++软件包不需要配置，只要您按照标准配置布局您的软件包，工具就会完成其余工作。

但是，如果您想提供额外的文档，如概念概述或教程，那么您将需要提供Sphinx conf.py 文件，并使用Sphinx在 .rst 文件中进行该文档。

另外，如果您有一个Python API，那么您将需要提供Sphinx conf.py

安装

先决条件

apt install -y python3-pip git

然后，安装 ros2_documentation 所需的软件包。

安装 rosdoc2

可以从git仓库本地安装 rosdoc2。克隆仓库，切换到目录，然后运行

pip install --user --upgrade .

rosdoc2 将安装在 ~/.local/bin/ 目录下。

文档

此工具的目的是在构建ROS 2软件包的文档时自动执行各种文档工具。此外，它还提供了一些开箱即用的行为，以最小化软件包中的配置并提供软件包间的一致性。

它旨在支持两个主要情况

• 无配置生成C++和Python API文档，并为简单软件包提供着陆页
• 自定义Doxyfile（对于C++）和Sphinx conf.py文件，用于更广泛的配置文档

第一个案例的目标是在软件包中几乎不需要配置的情况下，仍然提供一些有用的文档，即使没有Doxyfile、Sphinx conf.py文件或任何自由形式文档。

第二个案例的目标是允许软件包具有自由形式的文档，额外的Doxygen和Sphinx设置，以及使开发人员能够轻松手动调用Doxygen或Sphinx进行项目，而不使用此工具。在这种情况下，此工具将仅自动化工具的执行，并提供或覆盖某些其他设置，以使其与其他软件包更加一致，例如配置输出目录或提供使用Doxygen中的标签文件和Sphinx中的清单文件进行交叉引用所需的配置。

功能

此外，此工具旨在启用一些功能

• 所有软件包都具有基本软件包信息的统一着陆页
• 支持通过Doxygen提取C++ API文档
• 支持通过Sphinx提取Python API文档
• 支持通过Sphinx使用Sphinx支持自由形式文档（散文、教程、概念页面等）
• 支持使用Breathe通过Sphinx支持跨语言API交叉引用
• 支持使用Sphinx在软件包之间进行跨软件包文档交叉引用

路线图功能

在最初开发此工具时，考虑到了一些功能，但尚未实现。包括

• 可扩展的 "构建器"，以便将来可以支持其他类型的文档工具
• 如果软件包不需要，则在不首先构建软件包的情况下记录软件包
  • 需要首先构建包含生成的代码的包，包括包含ROS 2消息的包，但许多包并不需要这样做。
• 在自动化测试和/或CI中使用此工具。

构建包的文档

记录包

要使用此工具获取基本文档，您需要做的...什么也不需要。

此工具将从您的包的package.xml清单文件中提取信息，并为您生成一个着陆页。

此外，如果您的包按照标准方式布局，它将自动为您运行Sphinx和/或Doxygen。

但是，如果您需要将文件放在非标准位置，配置Sphinx和/或Doxygen超出默认设置，或者进行其他操作，您需要创建一个rosdoc2.yaml文件，并在您的包的package.xml中引用它。如何做到这一点，以及如何处理一些其他特殊情况，将在下面说明。

使用rosdoc2.yaml文件控制包的文档方式

要生成默认配置文件，请运行

rosdoc2 default_config \
  --package-path ./src/path/to/my_package_name

待办事项

具有C/C++ API文档的包

该工具使用您包的package.xml清单文件中的信息，并假设要提取文档的源文件都位于包的include文件夹中，这是基于ROS 2的包布局约定。

https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Developer-Guide.html#filesystem-layout

具有Python API文档的包

待办事项

具有Python和C/C++ API文档的包

待办事项

具有ROS 2消息和其他类型接口的包

待办事项

工作原理

在某些情况下，了解此工具如何工作可能有所帮助。

该工具遵循以下步骤

• 检查包的package.xml以查找任何rosdoc2特定配置。
  • 注意：如果没有找到，将使用默认配置，该配置尝试运行Sphinx和Doxygen。
  • 注意：配置包括构建段落，每个段落代表一个'builder'实例，形式为'output subdir': {<settings>}，位于'builders'键中。
    • 注意：'output subdir'是运行工具时指定的输出目录中的相对目录。
• 生成“包标题”的内容，该内容将位于包索引页面中（如果启用）或由用户的Sphinx项目包含。
  • 注意：这包含来自package.xml和其他来源的关于包的标准信息。
• 生成文档。对于指定的每个构建器（按定义的顺序）
  • 使用关联的设置调用构建器。
    • 注意：每个构建器都有自己的输出目录，这样在生成文档时就不会发生文件冲突。
  • 尝试将所有生成的文件移动到一个公共输出目录中。
    • 注意：如果在复制时文件或文件夹已存在，则发生错误。这样做是为了捕获构建器之间的“文件冲突”，否则可能会静默发生。
• 如果配置为这样做，则生成包索引页面。
• 将结果文件从公共输出目录移动到用户指定的输出目录。
  • 注意：此步骤可以覆盖现有文件，例如来自工具之前运行的文件，但不会删除不再由文档生成的文件，因此如果您删除或重命名文档的部分，您可能需要删除输出目录。

从上面的内容中需要注意的一些事项

• 由于构建器的键是输出目录，因此在一个输出目录中不可能运行多个构建器。
• 由于构建器按定义的顺序运行，如果其中一个构建器依赖于另一个构建器的输出，则需要按正确顺序定义它们。

Sphinx构建器

Sphinx构建器将尝试做几件事情以确保即使没有任何配置也能运行

• 如果提供了sphinx_sourcedir，它将断言其存在并使用它。
• 如果没有，它将在包的根目录下的传统 doc 目录中寻找一个 Sphinx 项目。
• 如果没有，它将设置一个临时的 Sphinx 项目并在包上运行。

最终默认值已经设置，即使对于只有 C++ 的包也是如此，这样我们可以通过 Sphinx 和 Breathe 启用包之间的交叉引用。

如果找到了现有的 Sphinx 项目，则将 conf.py Sphinx 配置扩展以根据 rosdoc2 配置启用特定的功能。此外，如果未在 conf.py 中指定，则从 package.xml 中填充 project、author、release 和 version 选项。

Doxygen 构建器

Doxygen 构建器将尝试在没有额外配置的情况下运行，按照以下步骤：

• 如果提供了 doxyfile 设置，它将断言它存在并使用它。
• 如果没有，它将在包的根目录中寻找 Doxyfile，如果存在则使用它。
• 如果没有，它将寻找传统的 include 目录，如果存在，它将设置一个默认的 Doxygen 文件并尝试记录 include 中的头文件。

最终默认值是尽可能地记录头文件（假设对于大多数 C++ 包来说是公共接口）。

联系信息

待办事项

测试

要安装 rosdoc2 的测试先决条件，请运行

pip install --user --upgrade .[test]

您可能想使用本地目录中的代码测试 rosdoc2，而不是每次更改时都重新运行安装。为此，请从包含此 README 的目录中运行（

python3 -m pytest

如果您想看到更多输出，请尝试使用 -rP 和/或 --log-level=DEBUG 选项。要限制特定测试，例如 "full_package" 测试，请使用 -k full_package

例如，要获取 full_package 测试的详细输出（即使对于已通过测试），请运行

python3 -m pytest -rP --log-level=DEBUG -k full_package

贡献

待办事项

已知问题

描述/错误消息	问题	解决方案
没有模块名为 'rclpy._rclpy_pybind11'	#66	不要源 colcon 工作空间。