RST指南¶

在内部 URL 中使用相对链接¶

如果您需要引用内部文档页面或不在当前页面所在目录中的文件，始终使用*相对文件路径*而不是*绝对文件路径*。绝对文件路径表示目标文件从其文件树的根目录的位置。相对文件路径使用智能符号（例如 ../，它指向父文件夹）来指示目标文件相对于源文档的位置。

示例¶

假设有以下源文件树：

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

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

绝对路径：
- 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
相对路径：
- ../prices.html
- variants.html

相对链接在可读性和稳定性方面明显优于绝对链接：引用可以在版本更新、文件夹名称更改和文件树重构中保留。

在第100个字符之前开始新的一行¶

在RST中，可以在不强制换行的情况下换行渲染的HTML。利用这个特性来编写 最多100个字符的行 。句子中的换行会在HTML中产生额外的空格。这意味着您不需要在行尾留下尾随的空格来分隔单词。

小技巧

你可以在分隔符（-->）的``menuselection``标记和超链接引用的任何位置安全地换行。对于``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``标记（参见：:ref:`contributing/menuselection`）来达到相同的效果。实际上，它会与文档的其余部分一致地呈现菜单链，并且如果我们切换到新的图表，它会自动适应。此标记内联使用如下：Sales ‣ Settings ‣ Products ‣ Variants``。

编写具有弹性的代码¶

更倾向于在有序列表中使用 #. 而不是 1., 2., 等等。这样做可以避免在添加新元素到列表时破坏编号的风险，并且更容易维护。
避免使用隐式超链接目标，而是更喜欢使用内部超链接目标。引用隐式目标 如何打印报价？ 更容易出错，而引用显式目标 _print_quotation 则不会出现在渲染的HTML中，因此更不可能被修改。

在超链接目标前缀中加入应用程序名称¶

由于超链接目标在整个文档中可见，当使用 ref 标记引用时，建议在目标名称前加上相关应用程序的名称。例如，将目标命名为 _amazon/form 而不是 _form 可以避免不必要的行为，并使目标的目的清晰明确。

不要破坏超链接目标¶

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

在超链接引用中使用单下划线后缀¶

虽然在大多数情况下，使用双下划线后缀可以用于经典的超链接引用，但不建议使用，因为双下划线通常表示匿名超链接引用。这是一种特殊的超链接引用，它使用仅由两个下划线组成的无名称超链接目标。

tl;dr: 双下划线后缀在某些情况下可用，但是不好的做法，请改用单下划线后缀。

Edit on GitHub