警告

您正在阅读的 ROS 2 文档版本已达到 EOL（生命周期结束），不再受官方支持。如果您想了解最新信息，请访问 Jazzy.

为 ROS 2 文档做出贡献

欢迎向本网站投稿。本页介绍了如何为 ROS 2 文档做出贡献。在贡献之前，请务必仔细阅读以下部分。

该网站采用 斯芬克斯特别是使用 斯芬克斯多版本.

分支结构

文件的源代码位于 ROS 2 文档 GitHub 代码库.该版本库为每个 ROS 2 发行版设置了一个分支，以处理发行版之间的差异。如果一个改动对所有 ROS 2 发行版都是通用的，则应在 滚动 分支（之后会根据情况进行回溯）。如果改动是针对特定的 ROS 2 发行版，则应在相应的分支中进行。

来源结构

网站的源文件都位于 消息来源 子目录。各种 sphinx 插件的模板位于 source/_templates.根目录包含本地构建网站进行测试所需的配置和文件。

在本地建立网站

首先安装位于 requirements.txt 锉刀

下一条命令将执行特定于用户的安装，这需要 ~/.local/bin/ 加入 $PATH:

pip3 install --user --upgrade -r requirements.txt

为了让 Sphinx 能够生成图表，必须使用 点子 命令必须可用。

sudo apt update ; sudo apt install graphviz

为一个分支机构建立网站

要只为该分支建立网站，请键入 生产 网页 在版本库的顶层。这是测试本地变更的推荐方法。

制作 html

构建过程可能需要一些时间。要查看输出结果，请打开 build/html/index.html 在浏览器中。

您还可以在本地运行文档测试（使用 doc8)，执行以下命令：

试作

为所有分支机构建立网站

要为所有分支建立网站，请键入 生产 多版本 从 滚动 分支。这样做有两个缺点：

  1. 多版本插件不知道如何进行增量构建，所以总是重建所有内容。这可能会很慢。

  2. 键入时 生产 多版本中列出的分支。 conf.py 文件。这意味着不会显示本地更改。

要在多版本输出中显示本地变更，必须先将变更提交到本地分支。然后必须编辑 conf.py 文件，并更改 分支机构白名单 变量来指向你的分支。

书写页面

ROS 2 文档网站使用 reStructuredText 格式，这是 Sphinx 默认使用的明文标记语言。本节简要介绍 reStructuredText 概念、语法和最佳实践。

您可以参考 reStructuredText 用户文档 了解详细的技术规格。

目录

用于生成目录的指令有两种、 .. toctree:： 和 .. 内容：：.......。 .. toctree:： 用于顶级页面，如 教程.rst 来设置其子页面的排序和可见性。该指令可创建左侧导航面板和页面内导航链接，链接到列出的子页面。它可以帮助读者了解不同文档部分的结构，并在页面之间进行导航。

.. 树::
   :maxdepth： 1

"(《世界人权宣言》) .. 内容：： 指令用于为特定页面生成目录。它会解析页面中的所有标题，并建立一个页面内嵌套目录。它可以帮助读者查看内容概览并在页面内进行导航。

"(《世界人权宣言》) .. 内容：： 指令支持定义嵌套部分的最大深度。使用 :深度： 2 只会在目录中显示章节和小节。

.. 内容:: 目录
   :深度： 2
   :local：

标题

文档中主要使用四种标题类型。请注意，符号的数量必须与标题的长度相匹配。

页面标题
=================

章节标题
--------------

2 分节标题
^^^^^^^^^^^^^^^^^^^

2.4 小节标题
~~~~~~~~~~~~~~~~~~~~~~~~

我们通常使用一位数为分节编号，两位数（点分隔）为教程和操作指南中的分节编号。

列表

明星 * 用于用项目符号和数字符号列出无序项目 #. 用于列出编号项。它们都支持嵌套定义，并会相应地呈现出来。

* 要点

  * 弹点嵌套
  * 弹点嵌套

* 要点

#. 第一项
#. 第二项

代码格式

内文代码的格式可使用 反刻 用于展示 突出显示 代码

内文代码的格式可使用 ``backticks`` 用于展示 突出显示 代码

页面内的代码块需要使用 .. 代码块:： 指令。 .. 代码块:： 支持代码高亮显示语法，例如 C++, YAML, 游戏机, 敲击等等。指令内的代码需要缩进。

.. 代码块:: C++

   int 主要(int 参数, 烧焦** 参数)
   {
      rclcpp::启动(参数, 参数);
      rclcpp::后旋(标准::共享<；参数类>；());
      rclcpp::关闭();
      返回 0;
   }

图片

可以使用 .. 图像：： 指令。

.. 图像:: images/turtlesim_follow1.png