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.

100 字符限制¶

在 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

良好示例：

要创建贷项通知，请前往会计 ‣ 客户 ‣ 发票，打开发票并点击贷项通知。
不良示例：

要创建贷项通知，请前往会计 ‣ 客户 ‣ 发票，打开发票并点击贷项通知。

菜单选择¶

使用 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 不应包含在菜单路径会计 ‣ 会计 ‣ 分录中：

文件¶

使用 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（图形用户界面）元素标记（方括号内）作为描述符。

图表视图由（面积图）图标表示。数据透视表视图由图标表示。

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.

使用此格式可以从非一开始编号。
从那里开始编号会自动生成。

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 的带自定义标签的链接。它们遵循以下语法： `标签 <URL>`_ 。

注解

在目标为另一个文档页面时，请使用文档页面超链接。
不要使用非描述性超链接标签。

例如，这是指向 Odoo 网站的外部超链接。

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

外部超链接别名¶

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

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

概念验证是一个简化版本，是预期变更主要方向的原型。 PoC 是常见的缩写。

.. _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 支持文档范围的元数据标记，这些标记为整个页面指定行为。它们必须放置在源文件顶部的冒号 (:) 之间。

元数据	用途
`显示内容`	使 toctree 页面可从导航菜单访问。
`显示目录`	在具有 `show-content` 元数据标记的页面上显示目录。
`隐藏页面目录`	隐藏“本页内容”侧边栏，并使用全页宽度显示内容。
`无搜索`	将文档从搜索结果中排除。
`孤立页面`	无需将文档包含在 toctree 中。
`代码列`	显示一个动态侧栏，可用于展示交互式教程或代码片段。例如，参见会计备忘单。
`自定义 CSS`	链接 CSS 文件（逗号分隔）到文件。
`自定义 JS`	链接 JS 文件（逗号分隔）到文档。
`类`	为文件的 `<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

RST 指南与速查表¶

格式化¶

超链接¶

内部 URL：相对链接¶

重构：超链接目标¶

超链接标签¶

缩进¶

100 字符限制¶

标题¶

标记¶

强调（斜体）¶

强强调（粗体）¶

技术术语（字面量）¶

定义¶

缩写¶

GUI（图形用户界面） 元素¶

菜单选择¶

文件¶

命令¶

图标¶

列表¶

项目符号列表¶

编号列表¶

嵌套列表¶

超链接¶

外部超链接¶

外部超链接别名¶

自定义锚点¶

文档页面超链接¶

文件下载超链接¶

图像¶

提示块（警戒框）¶

另请参阅¶

注意¶

提示¶

示例¶

练习¶

重要¶

警告¶

危险¶

自定义¶

表格¶

列表表格¶

网格表格¶

代码块¶

折叠块¶

内容标签页¶

基本标签页¶

嵌套标签页¶

分组标签页¶

代码标签页¶

卡片¶

Documentation

Content guidelines

RST guidelines

文档元数据¶

格式化提示¶

换行但不打断段落¶

转义标记符号¶

GUI（图形用户界面）元素¶