RST guidelines and cheat sheet¶

重要

We strongly recommend reading the 内容指南 and main 文档 pages before contributing.

Follow the RST guidelines below when contributing to the documentation to help maintain consistency with the rest of the documentation and facilitate the review process for the team:

Use formatting.
Be consistent with indentation.
Start a new line before the 100th character.

For hyperlinks:

Use relative links for internal URLs.
Do not break hyperlink targets when refactoring.
Do not use non-descriptive hyperlink labels.

格式化¶

Use specific formatting to improve clarity and readability. For example, apply 菜单选择 for menu paths, GUI 元素 for other user interface elements, such as fields, buttons, and options, 备注 for notes, 示例 for examples, etc.

注解

Add a blank line between different block elements, such as paragraphs, lists, and directives to ensure proper rendering and formatting.

超链接¶

Internal URLs: relative links¶

If you need to reference an internal documentation page or a file that is not located in the same directory as the current page, always use relative file paths instead of absolute file paths. This ensures that links remain valid even with version updates, folder name changes, and directory structure reorganizations.

An absolute file path indicates the target’s location from the root directory. A relative file path uses smart notations (such as ../ that redirects to the parent folder) to indicate the target’s location relative to that of the source document.

Example

注解

The purpose of the following example is to illustrate the difference between absolute and relative links. Always use Documentation page hyperlinks when referencing documentation pages.

Given the following source file tree:

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

A reference to prices.rst and variants.rst could be made from import.rst as follows:

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

Refactoring: hyperlink targets¶

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

Hyperlink labels¶

Do not use non-descriptive labels for hyperlinks.

Example

Good example (descriptive label):

Please refer to the Accounting documentation.

Bad example (non-descriptive label):

Please refer to this page.

Indentation¶

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

Use as many spaces at the beginning of an indented line as needed to align it with the first character of the markup in the line above. This usually implies three spaces, but you only need two for bulleted lists, for example.

Example

The first : is below the i (three spaces):

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

The :titlesonly: and page references start below the t (three spaces):

.. toctree::
   :titlesonly:

   payables/supplier_bills
   payables/pay

Continuation lines resume below the I’s of “Invoice” (two spaces):

- 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¶

In RST, it is possible to break a line without forcing a line break on the rendered HTML. Make use of this feature to write lines of maximum 100 characters. It is not necessary to leave a trailing whitespace at the end of a line to separate words.

小技巧

You can safely break a line on any space, even inside markups such as menuselection and doc.
Some external hyperlinks may exceed 100 characters, but leaving them on a single line is acceptable.

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`.

标题¶

For each formatting line (e.g., ===), write as many symbols (=) as there are characters in the header.

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

标题大小	格式化
标题1	======= Heading =======
标题2	Heading =======
标题3	Heading -------
标题4	Heading ~~~~~~~
标题5	Heading *******
标题6	Heading ^^^^^^^

重要

Each document must have exactly one H1 heading.

标记语言¶

强调（斜体）¶

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

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

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 元素¶

Use the guilabel markup to identify any text of the interactive user interface (e.g., labels).

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

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

注解

Avoid using the guilabel markup when referring to a concept or general term.

Example

Good example:

To create a credit note, go to Accounting ‣ Customers ‣ Invoices, open the invoice, and click Credit Note.
Bad example:

To create a Credit Note, go to Accounting ‣ Customers ‣ Invoices, open the Invoice, and click Credit Note.

菜单选择¶

Use the menuselection markup to guide users through a sequence of menus, starting with the app’s name.

To review sales performance, go to Sales ‣ Reporting ‣ Dashboard.

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

注解

Only include actual menu items in the menuselection markup:

Use the GUI 元素 markup for other user interface elements, such as buttons and section titles:

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`.

Do not include menu section names. For example, in the screenshot below, Journals should not be included in the menu path Accounting ‣ Accounting ‣ Journal Entries:

文件¶

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

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

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.

图标¶

Use the icon markup to add the class name of an icon. There are two icon sets used in Odoo: FontAwesome4 and Odoo UI. Follow the icon with its name as a GUI 元素 in brackets as a descriptor.

The graph view is represented by the (area chart) icon. The pivot view is represented by the icon.

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.

小技巧

Prefer the use of autonumbered lists with #. instead of 1., 2., etc. for better code resilience.

嵌套列表¶

小技巧

Add a blank line before the nested elements in lists.
Indent nested lists properly, with sub-items aligned under their parent item.

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

- This is the first item of a bulleted list.

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

超链接¶

外部超链接¶

External hyperlinks are links to a URL with a custom label. They follow the syntax: `label <URL>`_.

注解

Use documentation page hyperlinks when targeting another documentation page.
Do not use non-descriptive hyperlink labels.

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

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

外部超链接别名¶

External hyperlink aliases allow creating shortcuts for external hyperlinks. The definition syntax is as follows: .. _target: URL. There are two ways to reference them, depending on the use case:

target_ creates a hyperlink with the target name as label and the URL as reference. Note that the _ moved after the target.
`label <target_>`_ the label replaces the name of the target, and the target is replaced by the 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.

自定义锚点¶

Custom anchors follow the same syntax as external hyperlink aliases but without any URL. They allow referencing a specific part of a RST file by using the target as an anchor. When users click the reference, they are taken to the part of the documentation page where the target is defined.

The definition syntax is: .. _target:. There are two ways to reference them, both using the ref markup:

:ref:`target` creates a hyperlink to the anchor with the heading defined below as label.
:ref:`label <target>` creates a hyperlink to the anchor with the given label.

重要

As targets are visible from the entire documentation when referenced with the ref markup, prefix the target name with the app/section name and the file name, separated by slashes, e.g., accounting/taxes/configuration.

注解

Add custom anchors for all headings so they can be referenced from any documentation file or within Odoo using documentation links.
Notice that there is no _ at the end, contrary to what is done with external hyperlinks.

Please refer to the 超链接 section to learn more about relative links.

 .. _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>`.

Documentation page hyperlinks¶

The doc markup allows referencing a documentation page wherever it is in the file tree through a relative file path. There are two ways to use the markup, both using the doc markup:

:doc:`path_to_doc_page` creates a hyperlink to the documentation page with the title of the page as label.
:doc:`label <path_to_doc_page>` creates a hyperlink to the documentation page with the given label.

Please refer to the Accounting documentation to learn more about 客户发票.

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

重要

Use relative links for documentation page hyperlinks.

文件下载超链接¶

The download markup allows referencing files (that are not necessarily RST documents) within the source tree to be downloaded.

Download this module structure template to start building your module.

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

注解

Store the file alongside other media files and reference it using a relative link.

图片¶

The image markup allows inserting images in a document.

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

小技巧

Images should generally be aligned to the left, which is the default behavior. Use the align parameter to change the alignment, e.g., :align: center.
Use the alt parameter to add ALT 标签, e.g., :alt: Activating the developer mode in the Settings app.
Use the scale parameter to scale the image, e.g., :scale: 75%.

另请参阅

Content guidelines for images

警告块（劝告）¶

另请参阅¶

另请参阅

.. 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/>`_

备注¶

注解

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

.. 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 |
+-----------------------+--------------+---------------+

小技巧

使用 = 代替 - 来定义标题行。
移除 - 和 | 分隔符以合并单元格。
Make use of this convenient table generator to build tables. Then, copy-paste the generated formatting into your document.

代码块¶

Use the code-block directive to show example code. Specify the language (e.g., python, xml, etc.) to format the code according to the language’s syntax rules.

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 标记可能无法正常工作。特别是：

选项卡标题无法翻译。
A tab cannot contain headings.
An alert block cannot contain tabs.
A tab cannot contain custom anchors.

基本标签页¶

基本选项卡可用于将内容分成多个选项。使用 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) {}
         }

代码选项卡¶

Use the code-tab markup to create code tabs, which are essentially group tabs that treat the tabs’ content as a code block. Specify the language to format the code according to the language’s syntax rules. If a label is set, it is used for grouping tabs instead of the language name.

#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 supports document-wide metadata markups that specify a behavior for the entire page. They must be placed between colons (:) at the top of the source file.

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

格式化提示¶

换行但不分段¶

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

紧随换行符的第二行。

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

Escape markup symbols¶

Markup symbols escaped with backslashes (\) are rendered normally. For instance, this \*\*line of text\*\* with \*markup\* symbols is rendered as “this **line of text** with *markup* symbols”.

When it comes to backticks (`), which are used in many cases such as external hyperlinks, using backslashes for escaping is no longer an option because the outer backticks interpret enclosed backslashes and thus prevent them from escaping inner backticks. For instance, `\`this formatting\`` produces an [UNKNOWN NODE title_reference] error. Instead, ```this formatting``` should be used to produce the following result: `this formatting`.

另请参阅

Docutils documentation on reStructuredText directives and roles

Edit on GitHub