为ROS 2文档做出贡献 [待校准@385]

贡献网站欢迎。本页说明如何有助于ROS 2文档。请务必阅读以下部分仔细贡献。 [待校准@386]

这个场地是用 Sphinx, and more particularly using Sphinx multiversion 建造的。 [待校准@387]

分支结构 [待校准@388]

文档的源文件代码位于 ROS 2 Documentation GitHub repository 。该仓库每个ROS 2分布设置一个分支，以处理分布之间的差异。如果所有ROS 2分布都有更改，则应将其更改为 rolling 分支 (然后根据需要进行反向移植)。如果更改特定于特定的ROS 2分布，则应将其更改为相应的分支。 [待校准@389]

源结构 [待校准@390]

该站点的源文件都位于 source 子目录下。各种狮身人面像插件的模板位于 source/_templates 下。根目录包含lo调用y构建站点进行测试所需的配置和文件。 [待校准@391]

构建站点lo调用y [待校准@392]

首先，安装要求位于 requirements.txt 文件中。 [待校准@393]

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

为一个分支建立站点 [待校准@394]

为了只为这个分支建立站点，在仓库的顶层键入 make html 。这是测试本地更改的推荐方法。 [待校准@395]

make html

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

您还可以使用以下命令运行文档测试lo调用y (使用 doc8 ): [待校准@397]

make test

为所有分支机构建立站点 [待校准@398]

为所有分支建立场地，从 rolling 分支键入 make multiversion 。这有两个缺点: [待校准@399]

  1. multiversion插件不了解如何进行增量构建，因此它总是重建所有内容。这可能会很慢。 [待校准@400]

  2. 打字时 make multiversion ，总是检查确切分支列出 conf.py 文件。这意味着不会显示局部更改。 [待校准@401]

要在multiversion输出中显示本地更改，必须首先将更改提交到本地分支。然后你必须编辑 conf.py 文件改变 smv_branch_whitelist 变量指向分支。 [待校准@402]

书写页面 [待校准@403]

ROS 2文档网站使用 reStructuredText 格式，这是狮身人面像使用的默认明文标记语言。本节简要介绍了 reStructuredText 的概念、语法和最佳实践。 [待校准@404]

你可以参考 reStructuredText User Documentation 的详细技术规格。 [待校准@405]

目录

有两种类型的指令用于生成目录，“..托克特里:: `` and `` ..内容:: . The ``  ..toctree::''用于顶级页面，如 ``Tutorials.rst ，以设置其子页面的顺序和可见性。此指令创建左侧导航面板和页面内导航链接到列出的子页面。它帮助读者理解单独文档部分的结构并在页面之间导航。 [待校准@406]

.. toctree::
   :maxdepth: 1

“……Content::''指令用于生成该特定页面的目录。它解析页面中所有当前标题，并构建页面内嵌套的目录表。它可以帮助读者查看内容概述并在页面内导航。 [待校准@407]

“……目录:: `` directive supports the definition of maximum depth of nested sections. Using `` : 深度: 2'' 仅显示目录中的部分和小节。 [待校准@408]

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

标题 [待校准@409]

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

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

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

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

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

在教程和操作指南中，我们通常使用一位数字来编号小节，使用两位数字 (点分隔) 来编号小节。 [待校准@411]

列表 [待校准@412]

星星 * 用于列出带有项目符号和数字符号 “#” 的无序项目。用于列出编号项目。它们都支持嵌套定义，并将相应地呈现。 [待校准@413]

* bullet point

  * bullet point nested
  * bullet point nested

* bullet point

#. first listed item
#. second lited item

代码格式 [待校准@414]

文本内代码可以使用 backticks 来格式化，以显示 highlighted 代码。 [待校准@415]

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

需要使用 “captured捕获页面内的代码块。代码块:: `` directive. `` ..代码块:: `` supports code highlighting for syntaxes like `` c ++ ”、 YAML 、 console 、 bash 等。指令内部的代码需要缩进。 [待校准@416]

.. code-block:: C++

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

图像 [待校准@417]

可以使用 “inserted插入图像。图片:: “指令。 [待校准@418]

.. image:: images/turtlesim_follow1.png