为ROS 2文档做出贡献 [1572]

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

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

分支结构 [1575]

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

源码结构 [1577]

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

本地构建站点 [1579]

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

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

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

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

sudo apt update ; sudo apt install graphviz

为一个分支构建网站 [1587]

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

make html

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

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

make test

为所有分支构建站点 [1591]

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

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

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

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

编写页面 [1599]

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

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

目录 []

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

.. toctree::
   :maxdepth: 1

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

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

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

标题 [1605]

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

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

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

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

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

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

列表 [1608]

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

* bullet point

  * bullet point nested
  * bullet point nested

* bullet point

#. first listed item
#. second lited item

代码格式化 [1610]

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

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

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

.. code-block:: C++

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

图片 [1613]

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

.. image:: images/turtlesim_follow1.png