RST指南?

示例?

假設有以下源文件樹：

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

可以從 import.rst 中如下引用渲染后的 prices.html 和 variants.html ：

  1. 絕對路徑：

    • https://odoo.com/documentation/16.0/applications/sales/sales/products_prices/prices.html

    • https://odoo.com/documentation/16.0/applications/sales/sales/products_prices/products/variants.html

  2. 相對路徑：

    • ../prices.html

    • variants.html

相對鏈接在可讀性和穩定性方面明顯優于絕對鏈接：引用可以在版本更新、文件夾名稱更改和文件樹重構中保留。

在第100個字符之前開始新的一行?

在 RST 中，可以在不強制換行的情況下換行，以編寫 最多100個字符的行 。句子中的換行符會在 HTML 中產生額外的空格。這意味著您不需要在行末留下尾隨空格來分隔單詞。

小技巧

您可以在分隔符（ --> ）周圍以及超鏈接引用的任何位置安全地換行。對于 doc 、 ref 和 download 標記，這僅適用于引用的標簽部分。

示例：標記內的換行?

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

縮進要保持一致?

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

在縮進的行開頭使用盡可能多的空格，以使其與上一行標記的第一個字符對齊。這通常意味著需要3個空格，但對于項目列表只需要2個空格。

示例：第一個 : 在 i 下方（3個空格）?

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

示例： :titlesonly: 和頁面引用從 t （3個空格）以下開始?

.. toctree::
   :titlesonly:

   payables/supplier_bills
   payables/pay

例子：續行在“Invoice”的“I”下方繼續（2個空格）?

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

使用菜單選擇標記?

雖然使用字符 ? 和菜單名稱來指示用戶點擊哪些菜單是可以的，但最好使用 menuselection 標記（參見： 使用菜單選擇標記 ）來實現相同的效果。這樣可以使菜單鏈與文檔的其余部分一致，并且如果我們切換到新的圖形圖表，它會自動適應。此標記的內聯使用如下：`` 銷售 ? 設置 ? 產品 ? 變體 ``。

編寫具有彈性的代碼?

  • 在有序列表中，優先使用 #. 而不是 1. , 2. , 等等。這樣可以避免在添加新元素時破壞編號，更易于維護。

  • 避免使用隱式超鏈接目標，而是更喜歡使用內部超鏈接目標。引用隱式目標 如何打印報價？ 更容易出錯，而引用顯式目標 _print_quotation 則不會出現在渲染的HTML中，因此更不可能被修改。