为 ROS 2 文档做贡献

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

本网站使用 Sphinx 构建，更具体地说是使用 Sphinx 多版本。

分支结构 

文档的源代码位于 ROS 2 文档 GitHub 存储库中。此存储库为每个 ROS 2 发行版设置一个分支，以处理发行版之间的差异。如果更改是所有 ROS 2 发行版的共同更改，则应将其应用于 rolling 分支（然后根据需要进行反向移植）。如果更改特定于特定的 ROS 2 发行版，则应将其应用于相应的分支。

源结构 

站点的源文件都位于 source 子目录下。

各种 sphinx 插件的模板位于 source/_templates 下。

根目录包含在本地构建站点进行测试所需的配置和文件。

在本地构建站点 

首先创建 venv 来构建文档：

# activate the venv
python3 -m venv ros2doc

# activate venv
source ros2doc/bin/activate

并安装位于“requirements.txt”文件中的要求：

pip install -r requirements.txt -c constraints.txt

pip install -r requirements.txt -c constraints.txt

python -m pip install -r requirements.txt -c constraints.txt

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

sudo apt update ; sudo apt install graphviz

brew install graphviz

Download an installer from the Graphviz Download page and install it. Make sure to allow the installer to add it to the Windows %PATH%, otherwise Sphinx will not be able to find it.

为一个分支构建站点 

若要仅为此分支构建站点，请在存储库的顶层键入“make html”。这是测试本地更改的推荐方法。

make html

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

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

make test

通过 Github CI 查看站点 

对于 ROS 2 Docs 的小更改，您可以使用我们的 Github Actions 中生成的工件以呈现的 HTML 形式查看更改。 “构建”操作将整个 ROS Docs 生成为可下载的 Zip 文件，其中包含 docs.ros.org 的所有 HTML 此构建操作在通过测试操作和 lint 操作后触发。

要下载和查看您的更改，请先转到您的拉取请求，然后单击标题下的“检查”选项卡。在检查页面的左侧，单击“测试”部分下的“测试”部分，然后单击“构建”对话框。这将在右侧打开一个菜单，您可以在其中单击“上传文档工件”，然后滚动到底部以查看标题“工件下载 URL”下“压缩”HTML 文件的下载链接。

Steps to find rendered HTML files on ROS Github action

为所有分支构建站点 

要为所有分支构建站点，请从“rolling”分支键入“make multiversion”。这有两个缺点：

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

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

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

检查断开的链接 

要检查网站上的断开链接，请运行：

make linkcheck

这将检查整个站点是否存在断开的链接，并将结果输出到屏幕和“build/linkcheck”。

将页面从“ROS Wiki <https://wiki.ros.org>”迁移到 ROS 2 文档的第一步是确定页面是否需要迁移。通过搜索相关术语检查内容或类似内容是否可在 https://docs.ros.org/en/rolling 上找到。如果已经迁移，恭喜您！您已完成。如果尚未迁移，请考虑是否值得保留。您或其他人认为有用且经常参考的页面是很好的候选者，前提是它们尚未被其他文档取代。当前发行版不再支持的 ROS 项目和功能的页面不应迁移。

迁移 ROS Wiki 页面的下一步是确定迁移页面的正确位置。只有涵盖核心 ROS 概念的 ROS Wiki 页面才属于 ROS 文档，这些页面应迁移到 ROS 文档中的逻辑位置。应将特定于软件包的文档迁移到软件包源存储库中生成的软件包级别文档。软件包级别文档更新后，它将`作为软件包级别文档<https://docs.ros.org/en/rolling/p/>`__的一部分可见。如果您不确定是否以及将页面迁移到何处，请通过 https://github.com/ros2/ros2_documentation 或 https://discourse.ros.org 上的问题与我们联系。

一旦您确定 ROS Wiki 页面值得迁移，并在 ROS 文档中找到合适的着陆点，迁移过程的下一步就是设置迁移页面所需的转换工具。在大多数情况下，将单个 ROS Wiki 页面迁移到 ROS Docs 所需的唯一工具是`PanDoc <https://pandoc.org/>`_ 命令行工具和文本编辑器。大多数现代操作系统都支持 PanDoc，安装说明可在其网站上找到。值得注意的是，ROS Wiki 使用的是较旧的 wiki 技术 (MoinMoin)，因此使用的标记语言是 MediaWiki 格式的一种晦涩方言。我们发现，从 ROS Wiki 迁移页面的最简单方法是使用 PanDoc 将其从 HTML 转换为重构文本。

迁移 Wiki 文件 

克隆相应的存储库。如果您要将页面迁移到这里托管的官方文档，则应克隆 https://github.com/ros2/ros2_documentation。
为迁移的页面创建一个新的 Github 分支。我们建议使用类似“pagename-migration”的内容。

#. 使用 wget 或类似工具将相应的 ROS Wiki 页面下载到 html 文件中（例如“wget -O urdf.html https://wiki.ros.org/urdf”）。或者，您可以使用 Web 浏览器保存页面的 HTML。

#. 接下来，您需要删除下载文件中多余的 HTML 使用浏览器的开发人员模式，找到 Wiki 页面中第一个有用的 HTML 元素的名称。在大多数情况下，文件第三行（以 <head> 标记开始）到第一个 <h1> 标记开始之间的所有 HTML 都可以安全删除。

如果有目录，第一个有用的标记可能是 <h2> 标记。同样，ROS wiki 包含一些以 <div id="pagebottom"></div> 开头并在 </body></html> 上方结束的页脚文本也可以删除。

通过在 HTML 和重组文本之间运行 PanDoc 转换来转换您的 html 文件。

以下命令将 HTML 文件转换为等效的重组文本文件：pandoc -f html -t rst urdf.html > URDF.rst。

尝试使用 make html 命令构建新文档。

可能会出现需要您解决的错误和警告。

**仔细**阅读整个页面，确保材料是 ROS 2 的最新内容。

检查每个链接，确保它指向 docs.ros.org 上的适当位置。

内部文档引用必须更新，以指向等效的 ROS 2 材料。

除非绝对必要，否则更新后的文档不应指向 ROS Wiki。

此过程可能需要您大幅修改文档，并且可能需要提取多个 wiki 文件。

您应该验证文档中的每个代码示例在 ROS 2 下是否正常工作。

查找并下载旧文档中可能存在的任何图像。最简单的方法是右键单击浏览器并下载所有图像。或者，您可以通过在 HTML 文件中搜索“<img src>”标签来查找图像。
对于下载的每个图像文件，更新图像文件链接以指向 ROS Docs 的正确图像目录。

如果任何图像需要更新，或者可以用 Mermaid 图表替换，请进行此更改。请注意，目前仅在核心 ROS 2 文档中支持 Mermaid.js。

#. 文档完成后，使用适当的 Sphinx 命令将目录添加到新的第一个文档的顶部。此块应替换旧 ROS Wiki 中的任何现有目录。

#. 发出您的拉取请求。确保指向原始 ROS Wiki 文件以供参考。

您的拉取请求被接受后，请在原始 ROS Wiki 文章的页面顶部添加一条注释，指向新的文档页面。

有关此过程的实际示例，请参阅 ROS 2 文档和原始 ROS Wiki 中的 ROS 2 图像处理管道。完整的文档页面可在 ROS 2 image_pipeline 包文档中找到。

使用 GitHub Codespaces 构建站点 

首先，您需要有一个 GitHub 帐户（如果您没有，可以免费创建一个）。然后，您需要转到 ROS 2 文档 GitHub 存储库。之后，您可以在 Codespaces 中打开存储库，只需单击存储库页面上的“代码”按钮，然后从下拉菜单中选择“使用 Codespaces 打开”即可。

之后，您将被重定向到 Codespaces 页面，您可以在其中查看 Codespaces 创建的进度。完成后，浏览器中将打开一个 Visual Studio Code 选项卡。您可以通过单击顶部面板中的“终端”选项卡或按 Ctrl-J 来打开终端。

在此终端中，您可以运行任何您想要的命令，例如，您可以运行以下命令来仅为此分支构建站点：

make html

最后，要查看网站，您可以点击右下角面板上的“Go Live”按钮，然后它会在浏览器的新选项卡中打开该网站（您需要浏览到“build/html”文件夹）。

使用 Devcontainer 构建站点 

ROS 2 文档 GitHub 存储库还支持使用 Visual Studio Code 的 Devcontainer 开发环境。

这将使您能够更轻松地构建文档，而无需更改操作系统。

在执行以下步骤之前，请参阅：doc:使用 VSCode 和 Docker 设置 ROS 2 [社区贡献] 以安装 VS Code 和 Docker。

克隆存储库并启动 VS Code：

git clone https://github.com/ros2/ros2_documentation
cd ./ros2_documentation
code .

要使用``Devcontainer``，您需要在 VS Code 的扩展中搜索（CTRL+SHIFT+X）安装“远程开发”扩展。

然后，使用``View->Command Palette…``或``Ctrl+Shift+P``打开命令面板。搜索命令``Dev Containers: Reopen in Container``并执行它。这将自动为您构建开发 docker 容器。

要构建文档，请在 VS Code 中使用``View->Terminal``或``Ctrl+Shift+``和``New Terminal``打开终端。在终端内，您可以构建文档：

make html

编写页面 

ROS 2 文档网站使用 reStructuredText 格式，这是 Sphinx 使用的默认纯文本标记语言。

本节简要介绍 reStructuredText 概念、语法和最佳实践。

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

目录 

用于生成目录的指令有两种类型，.. toctree:: 和 .. content::。 .. 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

代码格式化 

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

需要使用``.. code-block::指令捕获页面内的代码块。 ``.. code-block::``支持``C++、YAML、console、``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

参考和链接 

外部链接

创建指向外部网页的链接的语法如下所示。

`ROS Docs <https://docs.ros.org>`_

上述链接将显示为 ROS Docs。请注意最后一个单引号后的下划线。

内部链接

:doc: 指令用于创建指向其他页面的文内链接。

:doc:`Quality of Service <../Tutorials/Quality-of-Service>`

请注意，使用的是文件的相对路径。

ref 指令用于创建指向页面特定部分的链接。

这些链接可以是当前页面或不同页面内的标题、图像或代码部分。

需要在所需对象之前定义显式目标。

在以下示例中，目标定义为标题“尝试一些示例”前一行的“_talker-listener”。

.. _talker-listener:

Try some examples
-----------------

现在可以创建从文档中任何页面到该标题的链接。

:ref:`talker-listener demo <talker-listener>`

此链接将使用 HTML 锚链接“#talker-listener”将读者导航到目标页面。

宏

宏可用于简化针对多个发行版的文档编写。

通过将宏名称包含在花括号中来使用宏。

例如，在“rolling”分支上生成 Rolling 的文档时：

Use	Becomes (for Rolling)	Example
{DISTRO}	rolling	ros-{DISTRO}-pkg
{DISTRO_TITLE}	Rolling	ROS 2 {DISTRO_TITLE}
{DISTRO_TITLE_FULL}	Rolling Ridley	ROS 2 {DISTRO_TITLE_FULL}
{REPOS_FILE_BRANCH}	rolling	git checkout {REPOS_FILE_BRANCH}

同一个文件可以在多个分支（即多个发行版）上使用，并且生成的内容将特定于发行版。