RST 指南与速查表¶

重要

我们强烈建议在贡献之前阅读内容指南和主文档页面。

在贡献文档时，请遵循以下 RST 指南，以帮助保持与文档其余部分的一致性，并促进团队的审查流程：

使用格式化。
保持缩进的一致性。
在第 100 个字符之前开始新的一行。

对于超链接：

对内部 URL 使用相对链接。
在重构时不要破坏超链接目标。
不要使用非描述性的超链接标签。

格式化¶

使用特定的格式来提高清晰度和可读性。例如，对菜单路径应用菜单选择，对其他用户界面元素（如字段、按钮和选项）应用 GUI 元素，对注释应用备注，对示例应用示例等。

注解

在不同的块元素之间添加空行，例如段落、列表和指令，以确保正确的渲染和格式化。

超链接¶

内部 URL：相对链接¶

如果需要引用与当前页面不在同一目录下的内部文档页面或文件，请始终使用 相对文件路径 而不是 绝对文件路径 。这样可以确保链接在版本更新、文件夹名称更改和目录结构重组后仍然有效。

绝对文件路径表示目标从根目录开始的位置。相对文件路径使用智能符号（例如 ../ 表示指向父文件夹）来表示目标相对于源文档的位置。

Example

注解

以下示例的目的是说明绝对链接和相对链接之间的区别。在引用文档页面时，请始终使用文档页面超链接。

给定以下源文件树：

documentation
├── content
│   └── applications
│   │   └── sales
│   │   │   └── sales
│   │   │   │   └── products_prices
│   │   │   │   │   └── products
│   │   │   │   │   │   └── import.rst
│   │   │   │   │   │   └── variants.rst
│   │   │   │   │   └── prices.rst

可以从 import.rst 中引用 prices.rst 和 variants.rst ，如下所示：

绝对路径：
- documentation/content/applications/sales/sales/products_prices/prices.rst
- documentation/content/applications/sales/sales/products_prices/products/variants.rst
相对路径：
- ../prices.rst
- variants.rst

重构：超链接目标¶

当重构（改进而不添加新内容）章节标题或超链接目标时，请注意不要破坏任何对这些目标的超链接引用，或相应地更新它们。

超链接标签¶

不要为超链接使用非描述性标签。

Example

好的示例（描述性标签）：

请参考会计文档。

错误示例（非描述性标签）：

请参考此页面。

缩进¶

只使用空格（不要使用制表符）。

在缩进行的开头使用所需数量的空格，以使其与上一行标记的第一个字符对齐。这通常意味着三个空格，但在项目符号列表中，例如，您只需要两个空格。

Example

第一个 : 在 i 的下方（三个空格）：

.. image:: media/example.png
   :alt: example

titlesonly: 和页面引用从 t 下方开始（三个空格）：

.. toctree::
   :titlesonly:

   payables/supplier_bills
   payables/pay

换行从 “Invoice” 的 I 下方继续（两个空格）：

- Invoice on ordered quantity: invoice the full order as soon as the sales order is confirmed.
- Invoice on delivered quantity: invoice on what was delivered even if it is a partial
  delivery.

100th-character limit¶

在 RST 中，可以在不强制 HTML 渲染时换行的情况下换行。利用此功能编写 最多 100 个字符的行。无需在行尾留下尾随空格来分隔单词。

小技巧

你可以在任何空格处安全地换行，即使在诸如 menuselection 和 doc 的标记内也是如此。
某些外部超链接可能超过 100 个字符，但将它们保留在单行上是可接受的。

Example

To register your seller account in Odoo, go to :menuselection:`Sales --> Configuration -->
Settings --> Amazon Connector --> Amazon Accounts` and click :guilabel:`Create`. You can find
the **Seller ID** under the link :guilabel:`Your Merchant Token`.

标题¶

对于每个格式行（例如，===），写入与标题中字符数量相同的符号（=）。

实际上，用于格式化的符号并不重要。只有它们编写的顺序才重要，因为它决定了装饰标题的大小。这意味着您可能会遇到不同的标题格式和不同的顺序，在这种情况下，您应该遵循文档中的格式。在任何其他情况下，请使用下面显示的格式。

标题大小	格式化
H1	======= Heading =======
H2	Heading =======
H3	Heading -------
H4	Heading ~~~~~~~
H5	Heading *******
H6	Heading ^^^^^^^

重要

每个文档必须包含 恰好一个 H1 标题。

标记语言¶

强调（斜体）¶

强调文本的一部分。文本以斜体呈现。

填写信息在保存表单之前。

Fill out the information *before* saving the form.

强调（加粗）¶

强调文本的一部分。文本以粗体呈现。

一个 子域名 是另一个域名的一部分。

A **subdomain** is a domain that is a part of another domain.

技术术语（字面意思）¶

用于书写技术术语或特定的插入值。该文本以字面形式呈现。

插入打印机的IP地址，例如， 192.168.1.25 。

Insert the IP address of your printer, for example, `192.168.1.25`.

定义¶

使用 dfn 标记来定义一个术语。

文档是用RST编写的，需要进行构建（转换为HTML）以显示得漂亮。

The documentation is written in RST and needs to be built (:dfn:`converted to HTML`) to
display nicely.

缩写¶

使用 abbr 标记来编写自定义缩写，它将显示为工具提示。

Odoo 使用 OCR 和人工智能技术来识别文档的内容。

Odoo uses :abbr:`OCR (optical character recognition)` and artificial intelligence
technologies to recognize the content of the documents.

GUI 元素¶

使用 guilabel 标记来标识交互式用户界面的任何文本（例如，标签）。

更新您的凭据，然后点击保存。

Update your credentials, then click on :guilabel:`Save`.

注解

在提及概念或通用术语时，避免使用 guilabel 标记。

Example

Good example:

要创建贷项通知单，请前往会计 ‣ 客户 ‣ 发票，打开发票，然后点击贷项通知单。
Bad example:

要创建贷项凭证，请前往会计 ‣ 客户 ‣ 发票，打开发票，然后点击贷项凭证。

菜单选择¶

使用 menuselection 标记引导用户通过一系列菜单，从应用程序的名称开始。

要查看销售业绩，请前往销售 ‣ 报表 ‣ 仪表板。

To review sales performance, go to :menuselection:`Sales --> Reporting --> Dashboard`.

注解

仅在 menuselection 标记中包含实际的菜单项：

使用 GUI 元素标记来表示其他用户界面元素，例如按钮和部分标题：

To configure the bill control policy, navigate to :menuselection:`Purchase --> Configuration
--> Settings`, and scroll down to the :guilabel:`Invoicing` section. Under :guilabel:`Bill
Control`, select either :guilabel:`Ordered quantities` or :guilabel:`Received quantities`.

不要包含菜单部分的名称。例如，在下面的截图中，Journals 不应包含在菜单路径 Accounting ‣ Accounting ‣ Journal Entries 中：

文件¶

使用 file 标记来指示文件路径或名称。

使用位于仓库根目录下的 redirects.txt 文件创建重定向。

Create redirections using the :file:`redirects.txt` file found at the root of the
repository.

命令¶

使用 command 标记突出显示命令。

运行命令 make clean html 来删除已有的构建文件并将文档构建为 HTML。

Run the command :command:`make clean html` to delete existing built files and build the
documentation to HTML.

图标¶

使用 icon 标记来添加图标的类名。Odoo 中使用了两个图标集：FontAwesome4 和 Odoo UI。在图标名称后加上 GUI 元素作为描述符，并用括号括起来。

图表视图由 (area chart) 图标表示。数据透视表视图由图标表示。

The graph view is represented by the :icon:`fa-area-chart` :guilabel:`(area chart)` icon.
The pivot view is represented by the :icon:`oi-view-pivot` icon.

列表¶

项目符号列表¶

这是一个项目符号列表。
它有两个项目，第二个项目使用了两行。

- This is a bulleted list.
- It has two items, the second
  item uses two lines.

编号列表¶

这是一个有序列表。
编号是自动的。

#. This is a numbered list.
#. Numbering is automatic.

使用此格式以数字而非1开始编号。
从那里开始编号是自动的。

6. Use this format to start the numbering
   with a number other than one.
#. The numbering is automatic from there.

小技巧

为了更好的代码弹性，建议使用 #. 自动编号列表，而不是 1., 2. 等。

嵌套列表¶

小技巧

在列表中的嵌套元素前添加一个空行。
缩进嵌套列表时，确保子项与其父项对齐。

这是一个项目符号列表的第一项。
1. 它有一个嵌套的编号列表
2. 有两个项目。

- This is the first item of a bulleted list.

  #. It has a nested numbered list
  #. with two items.

超链接¶

外部超链接¶

外部超链接是指向带有自定义标签的 URL 的链接。它们的语法如下：`label <URL>`_。

注解

使用文档页面超链接来指向另一个文档页面。
不要使用非描述性的超链接标签。

例如， 这是一个指向Odoo网站的外部超链接 <https://www.odoo.com> _。

For instance, `this is an external hyperlink to Odoo's website <https://www.odoo.com>`_.

外部超链接别名¶

外部超链接别名允许为外部超链接创建快捷方式。定义语法如下：.. _target: URL。根据使用场景，有两种引用方式：

target_ 创建一个超链接，目标名称作为标签，URL 作为引用。注意 _ 移动到了目标之后。
`label <target_>`_ 标签会替换目标名称，而目标会被替换为 URL。

一个 proof-of-concept <https://en.wikipedia.org/wiki/Proof_of_concept> _ 是一个简化版本，一个原型，用于达成对主要预期变化的一致。 PoC <https://en.wikipedia.org/wiki/Proof_of_concept> _ 是一个常见的缩写。

.. _proof-of-concept: https://en.wikipedia.org/wiki/Proof_of_concept

   A proof-of-concept_ is a simplified version, a prototype of what is expected to agree on
   the main lines of expected changes. `PoC <proof-of-concept_>`_ is a common abbreviation.

自定义锚点¶

自定义锚点遵循与外部超链接别名相同的语法，但不包含任何 URL。它们允许通过将目标用作锚点来引用 RST 文件中的特定部分。当用户点击引用时，他们将被带到定义目标的文档页面部分。

定义语法为：.. _target:。有两种引用它们的方式，都使用 ref 标记：

:ref:`target` 创建一个指向下方定义为标签的标题的锚点的超链接。
:ref:`label <target>` 创建一个指向具有给定标签的锚点的超链接。

重要

由于使用 ref 标记引用时，目标在整个文档中可见，因此请在目标名称前加上 应用/部分名称 和 文件名，并用斜杠分隔，例如 accounting/taxes/configuration。

注解

为所有标题添加自定义锚点，以便可以从任何文档文件或 Odoo 内部使用文档链接进行引用。
请注意，与外部超链接不同，末尾没有 _。

请参考超链接部分以了解更多关于相对链接的信息。

 .. _contributing/rst/hyperlinks-guidelines:

 Hyperlinks
 ==========

.. _contributing/rst/relative-links:

Use relative links for internal URLs
------------------------------------

Please refer to the :ref:`<contributing/rst/hyperlinks-guidelines>` section to learn more
about :ref:`relative links <contributing/rst/relative-links>`.

文档页面超链接¶

doc 标记允许通过相对文件路径引用文档页面，无论它在文件树中的哪个位置。有两种使用该标记的方式，两者都使用 doc 标记：

:doc:`path_to_doc_page` 创建一个指向文档页面的超链接，并使用页面标题作为标签。
:doc:`label <path_to_doc_page>` 创建一个带有给定标签的文档页面的超链接。

请参阅会计文档以了解更多关于客户发票的信息。

Please refer to the :doc:`Accounting documentation <../../../applications/finance/accounting>`
to learn more about :doc:`../../../applications/finance/accounting/customer_invoices`.

重要

使用相对链接用于文档页面超链接。

文件下载超链接¶

download 标记允许引用源树中的文件（不一定是 RST 文档）以供下载。

下载此 模块结构模板 以开始构建您的模块。

Download this :download:`module structure template <rst_guidelines/my_module.zip>` to start building your module.

注解

将文件与其他媒体文件一起存储，并使用相对链接进行引用。

图像¶

image 标记允许在文档中插入图像。

.. image:: rst_guidelines/create-invoice.png
   :alt: Create an invoice.

小技巧

图像通常应左对齐，这是默认行为。使用 align 参数来更改对齐方式，例如 :align: center。
使用 alt 参数来添加 ALT 标签，例如 :alt: 在设置应用中激活开发者模式。
使用 scale 参数来缩放图像，例如 :scale: 75%。

另请参阅

图像内容指南

警告块（劝告）¶

另请参阅¶

另请参阅

.. seealso::
- :doc:`Accounting documentation <../../../applications/finance/accounting>`
- :doc:`../../../applications/sales/sales/invoicing/proforma`
- `Google documentation on setting up Analytics for a website <https://support.google.com/analytics/answer/1008015?hl=en/>`_

备注¶

注解

使用此提示框来吸引读者的注意并突出显示重要的附加信息。

.. note::
   Use this alert block to draw the reader's attention and highlight important additional information.

提示¶

小技巧

使用此警告块向读者通知需要采取行动的有用技巧。

.. tip::
   Use this alert block to inform the reader about a useful trick that requires an action.

示例¶

Example

使用此警示块展示一个例子。

.. example::
   Use this alert block to show an example.

练习¶

Exercise

使用此警告块向读者建议一项练习。

.. exercise::
   Use this alert block to suggest an exercise to the reader.

重要¶

重要

使用此警告块通知读者重要信息。

.. important::
   Use this alert block to notify the reader about important information.

警告¶

警告

使用此警告块要求读者在警告中描述的内容上小心进行。

.. warning::
   Use this alert block to require the reader to proceed with caution with what is described in the warning.

危险¶

危险

使用此警告块来引起读者对严重威胁的注意。

.. danger::
   Use this alert block to bring the reader's attention to a serious threat.

自定义¶

标题

使用您选择的标题自定义此警告块。

.. admonition:: Title

   Customize this alert block with a **Title** of your choice.

桌子¶

列出表格¶

列表表格使用两级项目符号列表将数据转换为表格。第一级表示行，第二级表示列。

名称	国家	最喜欢的颜色
劳尔	黑山共和国	紫色
梅拉妮	法国	红色

.. list-table::
   :header-rows: 1
   :stub-columns: 1

   * - Name
     - Country
     - Favorite colour
   * - Raúl
     - Montenegro
     - Purple
   * - Mélanie
     - France
     - Turquoise

网格表格¶

网格表格代表渲染的表格，更加直观易用。

	衬衫	T恤衫
可用颜色	紫色	绿色
可用颜色	青绿色	橙色
袖子长度	长袖衣服	短袖

+-----------------------+--------------+---------------+
|                       | Shirts       | T-shirts      |
+=======================+==============+===============+
| **Available colours** | Purple       | Green         |
|                       +--------------+---------------+
|                       | Turquoise    | Orange        |
+-----------------------+--------------+---------------+
| **Sleeves length**    | Long sleeves | Short sleeves |
+-----------------------+--------------+---------------+

小技巧

使用 = 代替 - 来定义标题行。
移除 - 和 | 分隔符以合并单元格。
利用这个方便的表格生成器来构建表格。然后，将生成的格式复制粘贴到你的文档中。

代码块¶

使用 code-block 指令来展示示例代码。指定语言（例如 python、xml 等）以根据该语言的语法规则格式化代码。

def main():
    print("Hello world!")

.. code-block:: python

   def main():
       print("Hello world!")

剧透警告¶

Answer to the Ultimate Question of Life, the Universe, and Everything

.. spoiler:: Answer to the Ultimate Question of Life, the Universe, and Everything

   **42**

内容选项卡¶

警告

在某些情况下， tabs 标记可能无法正常工作。特别是：

选项卡标题无法翻译。
一个标签不能包含标题。
一个警告块不能包含制表符。
一个标签不能包含自定义锚点。

基本标签页¶

基本选项卡可用于将内容分成多个选项。使用 tabs 标记定义选项卡序列。然后使用 tab 标记定义每个选项卡，后跟标签。

专为Odoo在线用户提供的内容。

.. tabs::

   .. tab:: Odoo Online

      Content dedicated to Odoo Online users.

   .. tab:: Odoo.sh

      Alternative for Odoo.sh users.

   .. tab:: On-premise

      Third version for On-premise users.

嵌套标签页¶

选项卡可以嵌套在彼此内部。

离我们最近的恒星。

.. tabs::

   .. tab:: Stars

      .. tabs::

         .. tab:: The Sun

            The closest star to us.

         .. tab:: Proxima Centauri

            The second closest star to us.

         .. tab:: Polaris

            The North Star.

   .. tab:: Moons

      .. tabs::

         .. tab:: The Moon

            Orbits the Earth.

         .. tab:: Titan

            Orbits Jupiter.

分组标签页¶

组标签是根据组标签进行同步的特殊标签。当用户返回页面或访问具有选项卡组的另一个页面时，将记住最后选择的组并自动选择该组。 group-tab 标记用于定义组标签。

C++

int main(const int argc, const char **argv) {
    return 0;
}

def main():
    return

class Main {
    public static void main(String[] args) {}
}

.. tabs::

   .. group-tab:: C++

      C++

   .. group-tab:: Python

      Python

   .. group-tab:: Java

      Java

.. tabs::

   .. group-tab:: C++

      .. code-block:: c++

         int main(const int argc, const char **argv) {
             return 0;
         }

   .. group-tab:: Python

      .. code-block:: python

         def main():
             return

   .. group-tab:: Java

      .. code-block:: java

         class Main {
             public static void main(String[] args) {}
         }

代码选项卡¶

使用 code-tab 标记来创建代码选项卡，这些选项卡本质上是分组选项卡，它们将选项卡的内容视为代码块。指定语言以根据语言的语法规则格式化代码。如果设置了标签，则使用该标签来分组选项卡，而不是使用语言名称。

#include <iostream>

int main() {
    std::cout << "Hello World";
    return 0;
}

print("Hello World")

console.log("Hello World");

.. tabs::

   .. code-tab:: c++ Hello C++

      #include <iostream>

      int main() {
          std::cout << "Hello World";
          return 0;
      }

   .. code-tab:: python Hello Python

      print("Hello World")

   .. code-tab:: javascript Hello JavaScript

      console.log("Hello World");

卡片¶

Documentation

Use this guide to acquire the tools and knowledge you need to write documentation.

Step-by-step guide

Content guidelines

List of guidelines, tips, and tricks to help you create clear and effective content.

RST guidelines

List of technical guidelines to observe when writing with reStructuredText.

.. cards::

   .. card:: Documentation
      :target: ../documentation
      :tag: Step-by-step guide
      :large:

      Use this guide to acquire the tools and knowledge you need to write documentation.

   .. card:: Content guidelines
      :target: content_guidelines

      List of guidelines, tips, and tricks to help you create clear and effective content.

   .. card:: RST guidelines
      :target: rst_guidelines

      List of technical guidelines to observe when writing with reStructuredText.

文档元数据¶

Sphinx 支持文档范围的元数据标记，这些标记用于指定整个页面的行为。它们必须放在源文件顶部的冒号 (:) 之间。

元数据	目的
`show-content`	使toctree页面可以从导航菜单中访问。
`show-toc`	在具有 `show-content` 元数据标记的页面上显示目录表。
`hide-page-toc`	隐藏“本页内容”侧边栏，使用全页宽度显示内容。
`nosearch`	从搜索结果中排除该文档。
`orphan`	禁止将文档包含在目录树中。
`code-column`	显示一个动态的侧边栏，可用于显示交互式教程或代码片段。例如，参见：会计备忘单。
`custom-css`	将 CSS 文件（逗号分隔）链接到文件。
`custom-js`	将 JS 文件（逗号分隔）链接到文档。
`classes`	将指定的类分配给文件的 `<main/>` 元素。

格式化提示¶

换行但不分段¶

你将一行长文本分成两行 -> 这里 <- 但它会被渲染成一行。

紧随换行符的第二行。

| A first long line that you break in two
  -> here <- is rendered as a single line.
| A second line that follows a line break.

转义标记符号¶

用反斜杠（\）转义的标记符号会正常渲染。例如，this \*\*line of text\*\* with \*markup\* symbols 会被渲染为 “this **line of text** with *markup* symbols”。

当涉及到反引号（`）时，它们在许多情况下被使用，例如外部超链接，使用反斜杠进行转义不再是一个可行的选择，因为外部的反引号会解释包含的反斜杠，从而阻止它们转义内部的反引号。例如，`\`this formatting\`` 会产生一个 [UNKNOWN NODE title_reference] 错误。相反，应该使用 ```this formatting``` 来产生以下结果：`this formatting`。

另请参阅

Docutils 关于 reStructuredText 指令和角色的文档

Edit on GitHub