为 ROS 2 文档做出贡献

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

分支结构 

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

来源结构 

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

从 ROS 维基迁移页面 

将页面从 ROS 维基百科 ROS 2 文档的目的是确定页面是否需要迁移。检查以下网站是否有相关内容或类似内容 https://ros-2.com/rolling 搜索相关术语。如果已经迁移，那么恭喜你！你已经完成了。如果尚未迁移，那么请考虑是否值得保留。你或其他人认为有用并经常引用的页面都是很好的候选页面，前提是它们没有被其他文档取代。当前发行版不再支持的 ROS 项目和功能的页面不应迁移。

迁移 ROS Wiki 页面的下一步是确定迁移页面的正确位置。只有涉及 ROS 核心概念的 ROS Wiki 页面才属于 ROS 文档，这些页面应该迁移到 ROS 文档中的逻辑位置。软件包的具体文档应迁移到软件包源代码库中生成的软件包级文档中。一旦软件包级文档更新完毕，就可以看到作为软件包级文档的一部分.如果您不确定是否要迁移页面以及迁移到何处，请通过以下问题与我们联系 https://github.com/ros2/ros2_documentation 或在 https://discourse.ros.org.

一旦你确定某个 ROS Wiki 页面值得迁移，并在 ROS 文档中找到了合适的落脚点，迁移过程的下一步就是设置迁移页面所需的转换工具。在大多数情况下，将单个 ROS Wiki 页面迁移到 ROS 文档所需的唯一工具是泛文档 PanDoc 由命令行工具和文本编辑器组成。大多数现代操作系统都支持 PanDoc，安装说明可在其网站上找到。值得注意的是，ROS 维基使用的是一种较早的维基技术（MoinMoin），因此使用的标记语言是一种晦涩难懂的媒体维基格式。我们发现，从 ROS Wiki 移植页面的最简单方法是使用 PanDoc 将 HTML 转换为重新结构化的文本。

迁移维基文件 

克隆相应的版本库。如果要将页面迁移到此处托管的官方文档，则应克隆 https://github.com/ros2/ros2_documentation.
为迁移后的页面创建一个新的 Github 分支。我们建议 pagename-migration.
使用 wget 或类似工具将相应的 ROS Wiki 页面下载到 html 文件中（例如 wget -O urdf.html https://wiki.ros.org/urdf).或者，您也可以使用网络浏览器保存页面的 HTML 代码。
接下来，你需要删除下载文件中无关的 HTML 使用浏览器的开发者模式，找到维基页面中第一个有用的 HTML 元素的名称。在大多数情况下，从文件第三行开始的所有 HTML 都会被删除。 <head>； 标记，直到第一个 h1>； 标签可以安全地删除。在有目录的情况下，第一个有用的标签可能是一个 <h2>； 标签。同样，ROS 维基中的一些页脚文本也是以"...... "开头。 <div id="pagebottom"></div>； 并在 </body></html>； 也可以移除。
通过在 HTML 和重组文本之间运行 PanDoc 转换来转换 HTML 文件。以下命令可将 HTML 文件转换为等效的重组文本文件： "" -f 网页 -t 第一次 urdf.html >； URDF.rst.
尝试使用 生产网页 命令。您可能需要处理一些错误和警告。
小心检查每一个链接，确保其指向 docs.ros.org 上的适当位置。必须更新内部文档参考资料，使其指向 ROS 2 的相应资料。除非绝对必要，否则更新后的文档不应指向 ROS 维基。这一过程可能需要对文档进行较大改动，而且可能需要调用多个维基文件。您应该验证文档中的每一个代码示例都能在 ROS 2 下正常工作。
查找并下载旧文档中的任何图像。最简单的方法是在浏览器中点击右键，下载所有图片。或者，您也可以通过搜索以下内容来查找图片 <img src>； 标记。
为下载的每个图像文件更新图像文件链接，使其指向 ROS 文档的正确图像目录。如果有任何图像需要更新，或者可以用美人鱼请进行此更改。请注意，目前只有核心 ROS 2 文档支持 Mermaid.js。
文档完成后，使用适当的 Sphinx 命令在新的 rst 文档顶部添加目录。该区块应取代旧 ROS Wiki 中的任何现有目录。
发布拉取请求。确保指向原始 ROS Wiki 文件以供参考。
一旦您的拉取请求被接受，请在原始 ROS Wiki 文章的页面顶部添加一个注释，指向新的文档页面。

有关此过程的实际操作示例，请参阅《ROS 2 图像处理管道》和《ROS 2 图像处理管道》。 ROS 2 文档而在原文中 ROS 维基百科.已完成的文档页面可在 ROS 2 图像管道软件包文档.

使用 GitHub 代码空间构建网站 

首先，你需要有一个 GitHub 账户（如果没有，可以免费创建一个）。然后，您需要访问 ROS 2 文档 GitHub 代码库.之后，您可以在 Codespaces 中打开版本库，只需点击版本库页面上的 "代码 "按钮，然后从下拉菜单中选择 "使用 Codespaces 打开 "即可。

之后，您将被重定向到 Codespaces 页面，在那里可以看到创建 Codespaces 的进度。创建完成后，浏览器中将打开一个 Visual Studio Code 标签。您可以点击顶部面板的 "Terminal（终端）"选项卡或按下 Ctrl-J.

在这个终端中，你可以运行任何你想要的命令，例如，你可以运行下面的命令只为这个分支建立网站：

制作 html

最后，要查看网站，您可以点击右下角面板中的 "Go Live "按钮，然后，它将在浏览器的新标签页中打开网站（您需要浏览至 build/html 文件夹）。

书写页面 

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

参考资料和链接 

外部链接

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

ROS 文档 <https://docs.ros.org>；`_

上述链接将显示为 ROS 文档.注意最后一个单引号后面的下划线。

内部链接

"(《世界人权宣言》) 医生 指令用于创建指向其他页面的内文链接。

医生服务质量<.../教程/服务质量>`

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

"(《世界人权宣言》) 档号 指令用于创建指向页面特定部分的链接。这些部分可以是当前页面或不同页面中的标题、图片或代码部分。

需要在所需对象之前定义明确的目标。在下面的示例中，目标被定义为 对话者-听众 标题前一行 尝试一些例子.

.. _谈话者 -听众

举例说明
-----------------

现在，可以创建从文件中任何页面到该页眉的链接。

:参考：谈话者-听众演示 <talker-listener>`

该链接将引导读者通过 HTML 锚点链接进入目标页面 #谈话者-听众.

宏

宏可以用来简化针对多个发行版的文档编写工作。

使用宏时，请将宏名放在大括号中。例如，在为轧辊上的 滚动 分支：

使用	成为（用于滚动）	示例
{DISTRO}	滚动	ros-{DISTRO}-pkg
{DISTRO_TITLE}	滚动	ros 2 {distro_title}
{distro_title_full}	滚动的雷德利	ros 2 {distro_title_full}
{repos_file_branch} 文件分支	滚动	git checkout {REPOS_FILE_BRANCH}

同一文件可用于多个分支（即多个发行版），生成的内容将针对特定发行版。