RST速查表¶

标题¶

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

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

标题大小	格式化
标题1	======= Heading =======
标题2	Heading =======
标题3	Heading -------
标题4	Heading ~~~~~~~
标题5	Heading *******
标题6	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`.

文件¶

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

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

Create redirections with the :file:`redirects.txt` file 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.

列表¶

项目符号列表¶

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

- 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. 有两个项目。

- This is the first item of a bulleted list.

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

超链接¶

外部超链接¶

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

注解

URL可以是文档中文件的相对路径。
如果你的目标是另一个文档页面，请使用 documentation pages hyperlinks。

例如， 这是一个指向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。实际上，它们是内部的。它们允许通过使用目标作为锚点引用文档的特定部分。当用户单击引用时，文档将滚动到包含锚点的页面部分。

定义语法是： .. _target:

有两种引用它们的方式，都使用 ref 标记：

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

请参阅在内部 URL 中使用相对链接以了解如何编写适用于内部引用的正确相对链接。

注解

自定义锚点可以从定义它们的文件以外的其他文件中引用。
注意到末尾没有 _ ，与外部超链接的做法相反。

这可以通过创建一个新产品来轻松完成，有关更多帮助，请参阅如何创建一个产品？。

如何创建产品？

As explained at the start of the page, …

.. _sales/quotation/start-of-page:

This can easily be done by creating a new product, see :ref:`product` for additional help.

.. _sales/quotation/product:

How to create a product?
========================

As explained at the :ref:`start of the page <sales/quotation/start-of-page>`, ...

文档页面超链接¶

The doc markup allows referencing a documentation page wherever it is in the file tree through a relative file path.

通常情况下，有两种使用标记的方法：

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

请参考 this documentation 和 Send a pro-forma invoice。

Please refer to :doc:`this documentation <customer_invoices>` and to
:doc:`../sales/sales/invoicing/proforma`.

文件下载超链接¶

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

下载这个模块结构模板来快速开始构建你的模块。

Download this :download:`module structure template <extras/my_module.zip>` to start building your
module in no time.

图片¶

The image markup allows inserting images in a document.

.. image:: rst_cheat_sheet/create-invoice.png
   :align: center
   :alt: Create an invoice.

小技巧

在图像上添加 :class: o-no-modal 选项以防止在模态框中打开它。

警告块（劝告）¶

备注¶

注解

使用此警告块来引起读者对额外信息的注意。

.. note::
   Use this alert block to grab the reader's attention about 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 |
+-----------------------+--------------+---------------+

小技巧

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

代码块¶

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

选项卡标题无法翻译。
一个标签页不能包含 headings。
一个 alert block 不能包含制表符。
制表符中不能包含自定义锚点。

基本标签页¶

基本选项卡可用于将内容分成多个选项。使用 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 标记用于定义代码标签。与 code-block 标记一样，语言定义了标签的语法高亮。如果设置了标签，则使用标签而不是语言进行分组。

#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 and trips and tricks to make your content shine at its brightest!

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 and trips and tricks to make your content shine at its brightest!

   .. card:: RST guidelines
      :target: rst_guidelines

      List of technical guidelines to observe when writing with reStructuredText.

文档元数据¶

Sphinx支持文档范围的元数据标记，可以为整个页面指定行为。

它们必须放置在源文件的顶部，两边用冒号（:）括起来。

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

格式化提示¶

换行但不分段¶

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

紧随换行符的第二行。

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

Edit on GitHub