维基编辑风格指南

本页解释了维基使用的语法的一些特定部分，以及促进外观一致性和维基内容可维护性的一般风格指南。一般原则是保持简洁，尽量少用样式

欲了解更多信息，请查阅 Sphinx 重构文本入门.

创建新页面

提示

首先搜索维基，确定是否已经有一个关于你的主题的维基页面--与其创建一个近乎重复的主题，不如改进现有的主题！同时与 Discord 上的维基编辑器 或在 维基问题列表.

页面应在 /source/docs/ 文件夹，并给出一个 "描述性 "名称和文件后缀".rst"。通常情况下，我们使用小写字母作为文件名，并用"-"或"_"分隔单词。例如 高级旋翼飞行器设计.rst.

所有维基都通用的页面必须使用前缀"...... "来命名。 常见 必须在 /common/source/docs/.湖泊 使用常用页面 了解更多信息。

新页面的标题应简明扼要--信息量要足够大，以便读者判断该主题是否相关，并将其 与其他类似主题区分开来。除了 "a"、"with"、"and"、"the "等短连接词外，标题中每个单词的第一个字母都应大写。

标题前还应该有一个为页面命名的锚链接。因此，页面上的第一条信息应为

.. 您的文件名：

===============
您的页面标题
===============

使用常用页面

维基上有大量适用于所有不同类型载具用户的信息。为了减少（人工）重复，我们将这些主题定义在一个地方（如/common/source/docs)，并自动复制到其他需要的维基站点。

创建和编辑常用页面与编辑其他页面类似，但以下情况除外：

• 普通页面的文件名必须以以下文字开头 常见.例如，该页面是 共用维基编辑指南.rst.

• 所有常用页面必须存储在 /common/source/docs

• 可以在源代码末尾添加 copywiki 短代码，以指定目标维基的集合（使用 "copywiki "而不是下面的 "xcopywiki"）：

  [xcopywiki 目的地="旋翼飞行器、飞机"；]
  

• 如果未指定复制维基简码，普通页面将自动复制到旋翼飞行器、飞机和漫游车维基中

• 可以使用 地点 简码。在将通用页面复制到每个维基之前，不适用于目标维基的文本会被删除。下面的示例显示了只出现在UGV无人车和飞机维基上的文本（使用 site 而不是下面显示的 xsite！）。

  [xsite 维基="漫游车、飞机"；]无人车UGV 和 飞机 特定 文本[/xsite]
  

• 始终如一 链接到其他共同话题 使用相对链接。这样可以确保在复制维基文章时链接到正确的共同主题。

标题

选择一个简洁而具体的标题。标题应具有足够的信息量，使读者能够判断内容是否相关，同时又能将其与其他（类似）主题区分开来。

标题中所有单词均使用首字母大写（连接词除外："and"、"the"、"with "等）。

标题语法如下所示。请注意，我们在标题前使用了 "锚引用"（使用页面文件名命名）。这样，即使文件在文件结构中移动，我们也能从其他维基和文档链接到该文件。

.. 您的文件名称2：

==========
页面标题
==========

摘要

用摘要而不是标题或图片开头（在标题之后）。

最好用一句话或一小段文字描述主题的内容和范围。

标题

标题的创建方法是在标题文本上（完全）用一个字符下划线。我们使用以下级别：

标题 1
=========

标题 2
---------

标题 3
+++++++++

标题 4
^^^^^^^^^

标题 5
~~~~~~~~~

强调

应强调 俭用.页面中粗体或斜体过多会使人难以阅读，同时也会降低强调作为识别重要信息的工具的作用。

使用强调标记 类型 的信息：

• 代码 代码和变量

• 豪迈 按钮 "和文件名

• 斜体 对话框和工具的名称。

每种情况的加价如下。

内联代码
**粗体**
*意大利语*

列表

通过在一行开头使用 #. 后跟一个空格。无序列表可以用 "*"或"-"开头。创建嵌套列表时会进一步缩进：

# 排序列表

#. 项目一
#. 项目 2 多线
#. 项目 3

   - 嵌套项目
   #. 嵌套项目有序 #无序列表

- 项目 1
- 项目 2

  - 嵌套项目

信息说明和警告

您可以分别使用 "提示"、"注释 "和 "警告 "快捷代码在文本中添加注释、提示和警告。这些代码会在信息框中显示文本：

.. 备注::

   这是一份说明

备注

这是一份说明

.. 温馨提示::

   这是一个提示

提示

这是一个提示

.. 警告::

   这是一个警告

警告

这是一个警告

代码

使用 "代码块 "指令声明代码块。您还可以指定代码的类型，并对其进行语法标记：

.. 代码块:: 蟒蛇

    这 是 格式 对于 a 代码 区块 (于 蟒蛇)

    一些 代码

或者，你也可以在一行末尾加上双冒号"::"、空一行，然后缩进代码块文本：

这是代码块的格式：一些代码

内部链接

在文档集中链接到主题的最佳方法是使用指向命名锚点的引用链接。即使文档移动了，这个链接也能带你链接到主题，而且你可以跨维基链接到它。

锚点最好放在标题（或称谓）之前，格式如下所示（前面的下划线和后面的冒号很重要）：

.. _a_named_link：

提示

• 我们建议在每个页面的顶部放置一个锚点，用文章的文件名命名。

• 锚点必须是唯一的，因此使用页面锚点作为标题锚点的前缀

• 我们为您创建了许多有用的锚点；例如，要链接到一个参数，只需指定该参数为目标即可。

您可以使用以下两种方法之一，从同一维基链接到锚点：

:参考：a_named_link`  #链接到 "a_named_link"。显示锚点后的标题。
:参考：链接文本 <a_named_link>` 链接文本 <a_named_link>`  #链接到 "a_named_link"。显示指定文本。

您可以通过指定维基作为前缀，从另一个维基链接到锚点。例如，要链接到其他维基定义的这个锚点，你可以这样做：

:参考：copter:a_named_link`  #链接到旋翼飞行器维基中的"a_named_link"链接
:参考：链接文本<planner:a_named_link>`链接文本  #链接到规划器维基中的"a_named_link"链接

提示

对于维基中的链接和大多数常见主题，您可以使用 "裸 "格式。有时，您需要明确指定目标维基。

外部链接

要链接到维基以外的主题，请使用以下格式：

链接文本 <http://the-target-link-url>；`__

这种格式也可用于内部链接，但无法跟踪内部链接因标题更改等原因而中断的时间。

如何将页面放入侧边栏菜单

通过在父文章的 "toctree "指令中指定项目，可将其添加到侧边栏。文件名可以省略扩展名，但必须包含相对于当前目录的路径（维基中通常没有路径）。

.. 树::
    :maxdepth： 1 Pixhawk <common-pixhawk-overview> 显示文本<文件名>；

有时，父文章是 "通用 "的，但维基文章是特定维基的。在这种情况下，您可以使用 地点 简码（如下所示，但使用 "site "而不是 "xsite"）。您也可以忽略这种情况，但它会发出 "缺少文章 "的警告。

.. 树::
    :maxdepth： 1 Pixhawk <common-pixhawk-overview> [xsite wiki="漫游车、飞机"] 显示文本<文件名> [/xsite]

如何在顶部菜单中添加链接

顶部菜单链接被硬编码在 网站主题.

在维基页面中使用图片

我们对图像的一般建议是

• 图像尽可能小。

  提示

  图片存储在 Github 上，因此我们需要保持较小的整体大小。尽可能将图片裁剪为相关信息，并降低图片质量。

• 共同页面中的图片或对维基有用的图片应放在根目录中。 /图片 目录。

• 维基的特定图片可存储在其 /图片 子目录。

• 尽可能使用标题（"数字指令

• 如果图片大于页面可显示的尺寸，则链接到图片。

• 命名文件时使用小写字母，单词之间使用下划线。

• 给文件起一个 "有描述性 "的名字，以便于查找和重复使用。例如 planner2_flight_screen.jpg 比 image1.jpg.

• 要更改图像，只需替换源代码树中的文件并提交更改。

如下图所示，在 "普通 "文章中显示带有标题和目标的图片。请注意，文件的路径是相对于当前目录的（因此相对链接指向 图像 在项目根目录中）。

.. 数字:: .././././images/image_file_name.jpg
   :target： ../_images/image_file_name.jpg 标题文本

显示不带标题（或目标链接）的维基特定图片，如下图所示。请注意，路径是绝对的，是相对于 wiki 源目录的。

.. 图像:: /images/image_file_name.jpg