为ROS 2文档做出贡献

对这个网站的贡献是非常受欢迎的。本页面说明如何为ROS 2文档做出贡献。在贡献之前，请务必仔细阅读下面的章节。

该网站使用 Sphinx 构建，尤其使用了 Sphinx multiversion。

分支结构

文档的源代码位于 ROS 2 文档 GitHub 仓库。该仓库针对每个 ROS 2 版本分发设置了一个分支，以处理版本间的差异。如果一个更改适用于所有 ROS 2 版本，应该将其应用到 rolling 分支上（然后根据需要进行回溯合并）。如果一个更改仅适用于特定的 ROS 2 版本，应该将其应用到相应的分支上。

源码结构

站点的源文件都位于 source 子目录下。各种 Sphinx 插件的模板位于 source/_templates。根目录包含用于本地构建站点进行测试的配置文件和文件。

本地构建站点

首先安装位于 requirements.txt 文件中的依赖项：

接下来的命令执行用户特定的安装，需要将 ~/.local/bin/ 添加到 $PATH 中：

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

为了使Sphinx能够生成图表，必须可用``dot``命令。

sudo apt update ; sudo apt install graphviz

为一个分支构建网站

要为此分支构建网站，只需在存储库的顶层键入``make html``。这是测试本地更改的推荐方式。

make html

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

您还可以在本地运行文档测试（使用`doc8 <https://github.com/PyCQA/doc8>`_），使用以下命令：

make test

为所有分支构建站点

要为所有分支构建站点，请从``rolling``分支输入``make multiversion``命令。这有两个缺点：

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

  2. 当输入“make multiversion”时，它将始终检出在“conf.py”文件中列出的分支。这意味着本地更改将不会显示。

要在多版本输出中显示本地更改，您必须先将更改提交到本地分支。然后，您必须编辑“conf.py <https://github.com/ros2/ros2_documentation/blob/rolling/conf.py>`_”文件，并将“smv_branch_whitelist”变量更改为指向您的分支。

编写页面

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

你可以参考 reStructuredText用户文档 获取详细的技术规范。

目录

用于生成目录的指令有两种类型，.. toctree:: 和 .. contents::。.. toctree:: 用于顶级页面，如 Tutorials.rst，用于设置其子页面的排序和可见性。该指令同时创建左侧导航面板和页面内的导航链接，帮助读者了解单独文档部分的结构并在页面间导航。

.. toctree::
   :maxdepth: 1

.. contents:: 指令用于生成特定页面的目录。它解析页面中所有的标题，并构建一个页面内的嵌套目录。它帮助读者查看内容概览并在页面内导航。

.. contents:: 指令支持定义嵌套部分的最大深度。使用 :depth: 2 将只显示章节和子章节在目录中。

.. contents:: Table of Contents
   :depth: 2
   :local:

标题

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

Page Title Header
=================

Section Header
--------------

2 Subsection Header
^^^^^^^^^^^^^^^^^^^

2.4 Subsubsection Header
~~~~~~~~~~~~~~~~~~~~~~~~

我们通常在教程和操作指南中使用一位数字对子段进行编号，并使用两位数字（用点分隔）对子子段进行编号。

列表

星号 * 用于列出带有项目符号的无序项目，井号 #. 用于列出带有编号的项目。它们都支持嵌套定义，并将相应地呈现。

* bullet point

  * bullet point nested
  * bullet point nested

* bullet point

#. first listed item
#. second lited item

代码格式化

可以使用 反引号 来格式化内文代码，以显示 突出显示的 代码。

In-text code can be formatted using ``backticks`` for showing ``highlighted`` code.

页面内的代码块需要使用 .. code-block:: 指令进行捕获。 .. code-block:: 支持对诸如 C++、YAML、控制台、bash 等语法的代码进行突出显示。指令内的代码需要缩进。

.. code-block:: C++

   int main(int argc, char** argv)
   {
      rclcpp::init(argc, argv);
      rclcpp::spin(std::make_shared<ParametersClass>());
      rclcpp::shutdown();
      return 0;
   }

图片

可以使用``.. image::``指令插入图片。

.. image:: images/turtlesim_follow1.png