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.
编写具有弹性的代码¶
更倾向于在有序列表中使用
#.
而不是1.
,2.
, 等等。这样做可以避免在添加新元素到列表时破坏编号的风险,并且更容易维护。避免使用隐式超链接目标,而是更喜欢使用内部超链接目标。引用隐式目标
如何打印报价?
更容易出错,而引用显式目标_print_quotation
则不会出现在渲染的HTML中,因此更不可能被修改。
在超链接目标前缀中加入应用程序名称¶
由于超链接目标在整个文档中可见,当使用 ref
标记引用时,建议在目标名称前加上相关应用程序的名称。例如,将目标命名为 _amazon/form
而不是 _form
可以避免不必要的行为,并使目标的目的清晰明确。
不要破坏超链接目标¶
当重构(改进而不添加新内容)章节标题或超链接目标时,请注意不要破坏任何对这些目标的超链接引用,或相应地更新它们。