RST cheat sheet

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

H1

=======
Heading
=======

H2

Heading
=======

H3

Heading
-------

H4

Heading
~~~~~~~

H5

Heading
*******

H6

Heading
^^^^^^^

Важливо

Each document must have exactly one H1 heading. No less, no more.

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.

Приклад

This excerpt of RST: For instance, `this is a hyperlink reference <https://odoo.com>`_. is rendered as follows in HTML: “For instance, this is a hyperlink reference.”

Приклад

RST
.. _proof-of-concept: https://en.wikipedia.org/wiki/Proof_of_concept

A proof-of-concept_ is a simplified version, a prototype of what is expected to agree on the main
lines of expected changes. `PoC <proof-of-concept_>`_ is a common abbreviation.
Перегляд

A proof-of-concept is a simplified version, a prototype of what is expected to agree on the main lines of expected changes. PoC is a common abbreviation.

Приклад

RST
.. _sales/quotation/start-of-page:

This can easily be done by creating a new product, see :ref:`product` for additional help.

.. _sales/quotation/product:

How to create a product?
=========================

As explained at the :ref:`start of the page <sales/quotation/start-of-page>`, ...
Перегляд

This can easily be done by creating a new product, see How to create a product? for additional help.

How to create a product?

As explained at the start of the page, …

Приклад

RST
This can easily be done by creating a new user, see `How to create a new user?`_ for
additional help.  ...
Перегляд

This can easily be done by creating a new user, see How to create a new user? for additional help. …

The doc directive

The doc directive allows referencing a documentation page wherever it is in the file tree through a relative file path.
As usual, there are two ways to use the directive:
  1. :doc:`path_to_doc_page` creates a hyperlink reference to the documentation page with the title of the page as label.

  2. :doc:`label <path_to_doc_page>` creates a hyperlink reference to the documentation page with the given label.

Приклад

RST
Please refer to :doc:`this documentation <customer_invoices>` and to
:doc:`../sales/invoicing/proforma`.
Перегляд

Please refer to this documentation and to Send a pro-forma invoice.

The download directive

The download directive allows referencing files (that are not necessarily RST documents) within the source tree to be downloaded.

Приклад

RST
Download this :download:`module structure template <extras/my_module.zip>` to start building your
module in no time.
Перегляд

Download this module structure template to start building your module in no time.

The image directive

The image directive allows inserting images in a document. It comes with a set of optional parameter directives that can individually be omitted if considered redundant.

Приклад

RST
.. image:: media/create_invoice.png
   :align: center
   :alt: Create an invoice
   :height: 100
   :width: 200
   :scale: 50
   :class: img-thumbnail
   :target: ../invoicing.html#create-an-invoice
Перегляд
Create an invoice

Admonitions (alert blocks)

Seealso

RST

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

Перегляд

Дивись також

Примітка

RST

.. note::
   Use this admonition to grab the reader's attention about additional information.

Перегляд

Примітка

Use this admonition to grab the reader’s attention about additional information.

Чайові

RST

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

Перегляд

Порада

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

Exercise

RST

.. exercise::
Use this admonition to suggest an exercise to the reader.

Перегляд

Exercise

Use this admonition to suggest an exercise to the reader.

Важливий

RST

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

Перегляд

Важливо

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

Попередження

RST

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

Перегляд

Попередження

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

Небезпека

RST

.. danger::
   Use this admonition to bring the reader's attention to a serious threat.

Перегляд

Небезпека

Use this admonition to bring the reader’s attention to a serious threat.

Custom

RST

.. admonition:: Title

Customize this admonition with a **Title** of your choice.

Перегляд

Title

Customize this admonition with a Title of your choice.

Document metadata

Sphinx supports document-wide metadata directives that specify a behavior for the entire page.
They must be placed between colons (:) at the top of the source file.

Metadata

Purpose

show-content

Make a toctree page accessible from the navigation menu.

code-column

Show a dynamic side column that can be used to display interactive tutorials or code excerpts.

hide-page-toc

Hide the «On this page» sidebar and use full page width for the content.

custom-css

Link CSS files (comma-separated) to the document.

custom-js

Link JS files (comma-separated) to the document.

classes

Assign the specified classes to the <main/> element of the document.

orphan

Suppress the need to include the document in a toctree.

nosearch

Exclude the document from search results.

Formatting tips

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.

Перегляд

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 up your writing with specialized directives

Use these additional directives to fine-tune your content:

Directive

Purpose

Приклад

RST

HTML

abbr

Self-defining abbreviations

:abbr:`SO (Sales Order)`

SO

command

Highlight a command

:command:`python example.py`

python example.py

dfn

Define a term

:dfn:`a definition for a new term`

a definition for a new term

file

Indicate a file path

:file:`~/odoo/odoo-bin`

~/odoo/odoo-bin

menuselection

Guide a user through a sequence of menus

:menuselection:`Sales --> Configuration --> Settings`

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