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鏈接。它們遵循以下語法： `標簽 <URL>`_

注解

URL可以是文檔中文件的相對路徑。
如果你要鏈接到其他文檔頁面，請使用 documentation pages hyperlinks 。

例如，這是指向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。實際上，它們是內部的。它們允許通過使用目標作為錨點引用文檔的特定部分。當用戶單擊引用時，文檔將滾動到包含錨點的頁面部分。

定義語法為： .. _target:

有兩種引用它們的方式，都使用 ref 標記：

`` target `` 創建一個超鏈接到下面定義的標題錨點，并將其作為標簽。
`` label `` 創建一個超鏈接，指向給定標簽的錨點。

參見在內部 URL 中使用相對鏈接以了解如何為內部引用編寫正確的相對鏈接。

注解

自定義錨點可以從定義它們的文件以外的其他文件中引用。
注意，與外部超鏈接不同，末尾沒有 _ 。

這可以通過創建新產品輕松完成，請參閱 `如何創建產品？<https://example.com/product>`_ 獲取更多幫助。

如何創建產品？

如在頁面的 `開頭 <https://example.com/scroll-to-start-of-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>`, ...

文檔頁面超鏈接?

doc 標記允許通過相對文件路徑引用文件樹中的任何文檔頁面。

通常情況下，有兩種使用標記的方法：

`` path_to_doc_page `` 創建一個超鏈接到文檔頁面，標簽為頁面的標題。
`` label `` 創建一個超鏈接到給定標簽的文檔頁面。

請參考此文檔和發送形式發票。

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

文件下載超鏈接?

download 標記允許引用源代碼樹中的文件（不一定是 RST 文檔）進行下載。

下載此模塊結構模板，即可立即開始構建您的模塊。

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

圖片?

image 標記允許在文檔中插入圖片。

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

小技巧

在圖片上添加 :class: o-no-modal 選項，以防止在模態框中打開它。

警告塊（勸告）?

另請參閱?

另請參閱

客戶發票
形式發票

.. seealso::
   - :doc:`customer_invoices`
   - `Pro-forma invoices <../sales/sales/invoicing/proforma.html#activate-the-feature>`_

備注?

注解

使用此警告塊來引起讀者對額外信息的注意。

.. 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”標記可能在某些情況下無法正常工作。特別是：

選項卡標題無法翻譯。
制表符中不能包含標題。
警告塊（警告塊（勸告））不能包含制表符。
一個標簽頁中不能包含自定義錨點。

基本標簽頁?

基本選項卡可用于將內容分成多個選項。使用 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