RST guidelines

例子

Given the following source file tree:

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

A reference to the rendered prices.html and variants.html could be made from import.rst as follows:

  1. Absolute:

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

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

  2. Relative:

    • ../prices.html

    • variants.html

The relative links are clearly superior in terms of readability and stability: the references survive version updates, folder name changes and file tree restructurations.

Start a new line before the 100th character

In RST, it is possible to break a line without forcing a line break on the rendered HTML. Make use of this feature to write lines of maximum 100 characters. A line break in a sentence results in an additional whitespace in HTML. That means that you do not need to leave a trailing whitespace at the end of a line to separate words.

小技巧

You can safely break a line around the separators (-->) of menuselection directives and anywhere in a hyperlink reference. For the doc, ref and download directives, this is only true for the label part of the reference.

Example: Line breaks within directive and inline markup

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

Be consistent with indentation

Use only spaces (never tabs).

Use as many spaces at the beginning of an indented line as needed to align it with the first character of the directive in the line above. This usually implies 3 spaces but you only need 2 for bulleted lists.

Example: The first : is below the i (3 spaces)

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

Example: The :titlesonly: and page references start below the t (3 spaces)

.. toctree::
   :titlesonly:

   payables/supplier_bills
   payables/pay

Example: Continuation lines resume below the I’s of “Invoice” (2 spaces)

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

Use the menuselection directive

Although chaining characters and menu names works fine to indicate a user which menus to click, it is best to use the menuselection directive (see Spice up your writing with specialized directives) for the same result. Indeed, it renders the menus chain consistently with the rest of the documentation and would automatically adapt to the new graphic chart if we were to switch to a new one. This directive is used inline as follows: :menuselection:`Settings --> Products --> Variants`.

Write resilient code

  • Prefer the use of #. in numbered lists instead of 1., 2., etc. This removes the risk of breaking the numbering when adding new elements to the list and is easier to maintain.

  • Avoid using implicit hyperlink targets and prefer internal hyperlink targets instead. Referencing the implicit target How to print quotations? is more prone to break than a reference to the explicit target _print_quotation which never appears in the rendered HTML and is thus even less likely to be modified.