David Tran Contributing Hits: 28

Headings

For each formatting line (e.g., ===), write as many symbols (=) as there are characters in the header.
The symbols used for the formatting are, in fact, not important. Only the order in which they are written matters, as it determines the size of the decorated heading. This means that you may encounter different heading formatting and in a different order, in which case you should follow the formatting in place in the document. In any other case, use the formatting shown below.
Heading size Formatting Min/Max number of occurrences
H1
=======
Heading
=======
1/1
H2
Heading
=======
0/∞
H3
Heading
-------
0/∞
H4
Heading
~~~~~~~
0/∞
H5
Heading
*******
0/∞
H6
Heading
^^^^^^^
0/∞

Markup

Inline markup

Use the following markups to emphasize your text to your liking:

**Text** Text
*Text* Text
``Text`` Text

Bulleted list

- This is a bulleted list.
- It has two items, the second
  item uses two lines.
* This is a bulleted list too.
* The principle stays the same.

Numbered list

#. This is a numbered list.
#. Numbering is automatic.
1. This is a numbered list too.
2. Use this format to specify the numbering.

Nested lists

- This is the first item of a bulleted list.
  1. It has a nested numbered list
  2. with two items.

Admonitions (alert blocks)

Seealso

RST

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

Render

Note

RST

.. note::
   Use this to get the attention of the reader about additional information.

Render

Note

Use this to get the attention of the reader about additional information.

Tip

RST

.. tip::
   Use this to inform the reader about a useful trick that requires an
   action.

Render

Tip

Use this to inform the reader about a useful trick that requires an action.

Important

RST

.. important::
   Use this to notify the reader about an important information.

Render

Important

Use this to notify the reader about an important information.

Warning

RST

.. warning::
   Use this to require the reader to proceed with caution with what is
   described in the warning.

Render

Warning

Use this to require the reader to proceed with caution with what is described in the warning.

Danger

RST

.. danger::
   Use this to alarm the reader about a serious threat.

Render

!DANGER!

Use this to alarm the reader about a serious threat.

Formatting tips

Add banners on top of documents

Odoo feature

The Odoo theme supports banner images at the top of documents. At the first line of your documents, insert the directive :banner: banners/file_name.png. Replace file_name.png with the file that you placed in :file:`_static/banners` to server as a banner of your document.

Break the line but not the paragraph

RST

| First super long line that you break in two…
  here is rendered as a single line.
| Second line that follows a line break.

Render

First super long line that you break in two… here is rendered as a single line.
Second line that follows a line break.

Add comments

If you made a particular choice of writing or formatting that a future writer should be able to understand and take into account, consider writing a comment. Comments are blocks of text that do not count as a part of the documentation and that are used to pass a message to writers of the source code. They consist of a line starting with two dots and a space, followed by the comment.

.. For instance, this line will not be rendered in the documentation.

Use tables

Make use of this convenient table generator to build your tables. Then, copy-paste the generated formatting into your document.

Spice your writing with specialized directives

Use these additional directives to fine-tune your content:

Directive Purpose Example
RST HTML
abbr Self-defining abbreviations :abbr:`SO (Sales Order)` :abbr:`SO (Sales Order)`
command Highlight a command :command:`python example.py` :command:`python example.py`
dfn Define a term :dfn:`a definition for a new term` :dfn:`a definition for a new term`
file Indicate a file path :file:`~/odoo/odoo-bin` :file:`~/odoo/odoo-bin`
menuselection Guide a user through a sequence of menus :menuselection:`Sales --> Configuration --> Settings` :menuselection:`Sales --> Configuration --> Settings`

Escape markup symbols (Advanced)

Markup symbols escaped with backslashes (\) are rendered normally. For instance, this \*\*line of text\*\* with \*markup\* symbols is rendered as “this **line of text** with *markup* symbols”.

When it comes to backticks (`), which are used in many case such as :ref:`hyperlink references <contributing/hyperlink-references>`, using backslashes for escaping is no longer an option because the outer backticks interpret enclosed backslashes and thus prevent them from escaping inner backticks. For instance, `\`this formatting\`` produces an [UNKNOWN NODE title_reference] error. Instead, ```this formatting``` should be used to produce the following result: `this formatting`.