:custom-css: showcase_tables.css =============== RST cheat sheet =============== .. _contributing/headings: 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 | .. code-block:: text | | | | | | ======= | | | Heading | | | ======= | +--------------+----------------------+ | H2 | .. code-block:: text | | | | | | Heading | | | ======= | +--------------+----------------------+ | H3 | .. code-block:: text | | | | | | Heading | | | ------- | +--------------+----------------------+ | H4 | .. code-block:: text | | | | | | Heading | | | ~~~~~~~ | +--------------+----------------------+ | H5 | .. code-block:: text | | | | | | Heading | | | ******* | +--------------+----------------------+ | H6 | .. code-block:: text | | | | | | Heading | | | ^^^^^^^ | +--------------+----------------------+ .. important:: Each document must have **exactly one H1 heading**. No less, no more. .. _contributing/markups: Markups ======= .. _contributing/markups/italic: Emphasis (italic) ----------------- To emphasize a part of the text. The text is rendered in italic. .. list-table:: :class: o-showcase-table * - Fill out the information *before* saving the form. * - .. code-block:: text Fill out the information *before* saving the form. .. _contributing/markups/bold: Strong emphasis (bold) ---------------------- To emphasize a part of the text. The text is rendered in bold. .. list-table:: :class: o-showcase-table * - A **subdomain** is a domain that is a part of another domain. * - .. code-block:: text A **subdomain** is a domain that is a part of another domain. .. _contributing/markups/code-sample: Technical term (literal) ------------------------ To write a technical term or a specific value to insert. The text is rendered in literal. .. list-table:: :class: o-showcase-table * - Insert the IP address of your printer, for example, `192.168.1.25`. * - .. code-block:: text Insert the IP address of your printer, for example, `192.168.1.25`. .. _contributing/markups/definitions: Definitions ----------- Use the `dfn` markup to define a term. .. list-table:: :class: o-showcase-table * - The documentation is written in RST and needs to be built (:dfn:`converted to HTML`) to display nicely. * - .. code-block:: text The documentation is written in RST and needs to be built (:dfn:`converted to HTML`) to display nicely. .. _contributing/markups/abbreviations: Abbreviations ------------- Use the `abbr` markup to write a self-defining abbreviation that is displayed as a tooltip. .. list-table:: :class: o-showcase-table * - Odoo uses :abbr:`OCR (optical character recognition)` and artificial intelligence technologies to recognize the content of the documents. * - .. code-block:: text Odoo uses :abbr:`OCR (optical character recognition)` and artificial intelligence technologies to recognize the content of the documents. .. _contributing/markups/guilabel: :abbr:`GUI (graphical user interface)` element ---------------------------------------------- Use the `guilabel` markup to identify any text of the interactive user interface (e.g., button labels, view titles, field names, lists items, ...). .. list-table:: :class: o-showcase-table * - Update your credentials, then click on :guilabel:`Save`. * - .. code-block:: text Update your credentials, then click on :guilabel:`Save`. .. _contributing/markups/menuselection: Menu selection -------------- Use the `menuselection` markup to guide the user through a sequence of menus. .. list-table:: :class: o-showcase-table * - To review your sales performance, go to :menuselection:`Sales --> Reporting --> Dashboard`. * - .. code-block:: text To review your sales performance, go to :menuselection:`Sales --> Reporting --> Dashboard`. .. _contributing/markups/file: File ---- Use the `file` markup to indicate a file path or name. .. list-table:: :class: o-showcase-table * - Create redirections with the :file:`redirects.txt` file at the root of the repository. * - .. code-block:: text Create redirections with the :file:`redirects.txt` file at the root of the repository. .. _contributing/markups/command: Command ------- Use the `command` markup to highlight a command. .. list-table:: :class: o-showcase-table * - Run the command :command:`make clean html` to delete existing built files and build the documentation to HTML. * - .. code-block:: text Run the command :command:`make clean html` to delete existing built files and build the documentation to HTML. .. _contributing/markups/icons: Icons ----- Use the `icon` markup to add a class name of an icon. There are two icon sets used in Odoo: `FontAwesome4 `_ and :doc:`Odoo UI `. It is recommended to accompany an icon with a :ref:`contributing/markups/guilabel` as a descriptor, however, it is not mandatory. .. list-table:: :class: o-showcase-table * - The graph view is represented by the :icon:`fa-area-chart` :guilabel:`(area chart)` icon. The pivot view is represented by the :icon:`oi-view-pivot` icon. * - .. code-block:: text The graph view is represented by the :icon:`fa-area-chart` :guilabel:`(area chart)` icon. The pivot view is represented by the :icon:`oi-view-pivot` icon. .. _contributing/lists: Lists ===== .. _contributing/bulleted-list: Bulleted list ------------- .. list-table:: :class: o-showcase-table * - - This is a bulleted list. - It has two items, the second item uses two lines. * - .. code-block:: text - This is a bulleted list. - It has two items, the second item uses two lines. .. _contributing/numbered-list: Numbered list ------------- .. list-table:: :class: o-showcase-table * - #. This is a numbered list. #. Numbering is automatic. * - .. code-block:: text #. This is a numbered list. #. Numbering is automatic. .. list-table:: :class: o-showcase-table * - 6. Use this format to start the numbering with a number other than one. #. The numbering is automatic from there. * - .. code-block:: text 6. Use this format to start the numbering with a number other than one. #. The numbering is automatic from there. .. tip:: Prefer the use of autonumbered lists with `#.` for better code resilience. .. _contributing/nested-list: Nested lists ------------ .. list-table:: :class: o-showcase-table * - - This is the first item of a bulleted list. #. It has a nested numbered list #. with two items. * - .. code-block:: text - This is the first item of a bulleted list. #. It has a nested numbered list #. with two items. .. _contributing/hyperlinks: Hyperlinks ========== .. _contributing/external-hyperlinks: External hyperlinks ------------------- External hyperlinks are links to a URL with a custom label. They follow this syntax: ```label `_`` .. note:: - The URL can be a relative path to a file within the documentation. - Use the :ref:`documentation pages hyperlinks ` if you target another documentation page. .. list-table:: :class: o-showcase-table * - For instance, `this is an external hyperlink to Odoo's website `_. * - .. code-block:: text For instance, `this is an external hyperlink to Odoo's website `_. .. _contributing/external-hyperlink-aliases: External hyperlink aliases -------------------------- | External hyperlink aliases allow creating shortcuts for external hyperlinks. | The definition syntax is as follows: ``.. _target: URL`` | There are two ways to reference them, depending on the use case: #. ``target_`` creates a hyperlink with the target name as label and the URL as reference. Note that the ``_`` moved after the target! #. ```label `_`` does exactly what you expect: the label replaces the name of the target, and the target is replaced by the URL. .. list-table:: :class: o-showcase-table * - 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. * - .. code-block:: text .. _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 `_ is a common abbreviation. .. _contributing/custom-anchors: Custom anchors -------------- Custom anchors follow the same syntax as external hyperlink aliases but without any URL. Indeed, they are internal. They allow referencing a specific part of a document by using the target as an anchor. When the user clicks on the reference, the documentation scrolls to the part of the page containing the anchor. | The definition syntax is: ``.. _target:`` | There are two ways to reference them, both using the ``ref`` markup: #. ``:ref:`target``` creates a hyperlink to the anchor with the heading defined below as label. #. ``:ref:`label ``` creates a hyperlink to the anchor with the given label. See :ref:`contributing/relative-links` to learn how to write proper relative links for internal references. .. note:: - Custom anchors can be referenced from other files than the ones in which they are defined. - Notice that there is no ``_`` at the end, contrary to what is done with :ref:`external hyperlinks `. .. list-table:: :class: o-showcase-table * - 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 `_, ... * - .. code-block:: text .. _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 `, ... .. _contributing/doc-pages-hyperlinks: Documentation pages hyperlinks ------------------------------ | The ``doc`` markup 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 markup: #. ``:doc:`path_to_doc_page``` creates a hyperlink to the documentation page with the title of the page as label. #. ``:doc:`label ``` creates a hyperlink to the documentation page with the given label. .. list-table:: :class: o-showcase-table * - Please refer to `this documentation `_ and to `Send a pro-forma invoice `_. * - .. code-block:: text Please refer to :doc:`this documentation ` and to :doc:`../sales/sales/invoicing/proforma`. .. _contributing/download: File download hyperlinks ------------------------ The ``download`` markup allows referencing files (that are not necessarily :abbr:`RST (reStructuredText)` documents) within the source tree to be downloaded. .. list-table:: :class: o-showcase-table * - Download this `module structure template `_ to start building your module in no time. * - .. code-block:: text Download this :download:`module structure template ` to start building your module in no time. .. _contributing/image: Images ====== The ``image`` markup allows inserting images in a document. .. list-table:: :class: o-showcase-table * - .. image:: rst_cheat_sheet/create-invoice.png :align: center :alt: Create an invoice. * - .. code-block:: text .. image:: rst_cheat_sheet/create-invoice.png :align: center :alt: Create an invoice. .. tip:: Add the :code:`:class: o-no-modal` `option `_ to an image to prevent opening it in a modal. .. _contributing/alert-blocks: Alert blocks (admonitions) ========================== .. _contributing/seealso: See also -------- .. list-table:: :class: o-showcase-table * - .. seealso:: - `Customer invoices `_ - `Pro-forma invoices `_ * - .. code-block:: text .. seealso:: - :doc:`customer_invoices` - `Pro-forma invoices <../sales/sales/invoicing/proforma.html#activate-the-feature>`_ .. _contributing/note: Note ---- .. list-table:: :class: o-showcase-table * - .. note:: Use this alert block to grab the reader's attention about additional information. * - .. code-block:: text .. note:: Use this alert block to grab the reader's attention about additional information. .. _contributing/tip: Tip --- .. list-table:: :class: o-showcase-table * - .. tip:: Use this alert block to inform the reader about a useful trick that requires an action. * - .. code-block:: text .. tip:: Use this alert block to inform the reader about a useful trick that requires an action. .. _contributing/example: Example ------- .. list-table:: :class: o-showcase-table * - .. example:: Use this alert block to show an example. * - .. code-block:: text .. example:: Use this alert block to show an example. .. _contributing/exercise: Exercise -------- .. list-table:: :class: o-showcase-table * - .. exercise:: Use this alert block to suggest an exercise to the reader. * - .. code-block:: text .. exercise:: Use this alert block to suggest an exercise to the reader. .. _contributing/important: Important --------- .. list-table:: :class: o-showcase-table * - .. important:: Use this alert block to notify the reader about important information. * - .. code-block:: text .. important:: Use this alert block to notify the reader about important information. .. _contributing/warning: Warning ------- .. list-table:: :class: o-showcase-table * - .. warning:: Use this alert block to require the reader to proceed with caution with what is described in the warning. * - .. code-block:: text .. warning:: Use this alert block to require the reader to proceed with caution with what is described in the warning. .. _contributing/danger: Danger ------ .. list-table:: :class: o-showcase-table * - .. danger:: Use this alert block to bring the reader's attention to a serious threat. * - .. code-block:: text .. danger:: Use this alert block to bring the reader's attention to a serious threat. .. _contributing/custom-alert-blocks: Custom ------ .. list-table:: :class: o-showcase-table * - .. admonition:: Title Customize this alert block with a **Title** of your choice. * - .. code-block:: text .. admonition:: Title Customize this alert block with a **Title** of your choice. .. _contributing/tables: Tables ====== List tables ----------- List tables use two-level bulleted lists to convert data into a table. The first level represents the rows and the second level represents the columns. .. list-table:: :class: o-showcase-table * - .. list-table:: :header-rows: 1 :stub-columns: 1 * - Name - Country - Favorite color * - Raúl - Montenegro - Purple * - Mélanie - France - Red * - .. code-block:: text .. list-table:: :header-rows: 1 :stub-columns: 1 * - Name - Country - Favorite colour * - Raúl - Montenegro - Purple * - Mélanie - France - Turquoise Grid tables ----------- Grid tables represent the rendered table and are more visual to work with. .. list-table:: :class: o-showcase-table * - +-----------------------+--------------+---------------+ | | Shirts | T-shirts | +=======================+==============+===============+ | **Available colours** | Purple | Green | | +--------------+---------------+ | | Turquoise | Orange | +-----------------------+--------------+---------------+ | **Sleeves length** | Long sleeves | Short sleeves | +-----------------------+--------------+---------------+ * - .. code-block:: text +-----------------------+--------------+---------------+ | | Shirts | T-shirts | +=======================+==============+===============+ | **Available colours** | Purple | Green | | +--------------+---------------+ | | Turquoise | Orange | +-----------------------+--------------+---------------+ | **Sleeves length** | Long sleeves | Short sleeves | +-----------------------+--------------+---------------+ .. tip:: - Use `=` instead of `-` to define header rows. - Remove `-` and `|` separators to merge cells. - Make use of `this convenient table generator `_ to build your tables. Then, copy-paste the generated formatting into your document. .. _contributing/code-blocks: Code blocks =========== .. list-table:: :class: o-showcase-table * - .. code-block:: python def main(): print("Hello world!") * - .. code-block:: text .. code-block:: python def main(): print("Hello world!") .. _contributing/spoilers: Spoilers ======== .. list-table:: :class: o-showcase-table * - .. spoiler:: Answer to the Ultimate Question of Life, the Universe, and Everything **42** * - .. code-block:: text .. spoiler:: Answer to the Ultimate Question of Life, the Universe, and Everything **42** .. _contributing/tabs: Content tabs ============ .. caution:: The `tabs` markup may not work well in some situations. In particular: - The tabs' headers cannot be translated. - A tab cannot contain :ref:`headings `. - An :ref:`alert block ` cannot contain tabs. - A tab cannot contain :ref:`custom anchors `. .. _contributing/tabs/basic: Basic tabs ---------- Basic tabs are useful to split the content into multiple options. The `tabs` markup is used to define sequence of tabs. Each tab is then defined with the `tab` markup followed by a label. .. list-table:: :class: o-showcase-table * - .. tabs:: .. tab:: Odoo Online Content dedicated to Odoo Online users. .. tab:: Odoo.sh Alternative for Odoo.sh users. .. tab:: On-premise Third version for On-premise users. * - .. code-block:: text .. tabs:: .. tab:: Odoo Online Content dedicated to Odoo Online users. .. tab:: Odoo.sh Alternative for Odoo.sh users. .. tab:: On-premise Third version for On-premise users. .. _contributing/tabs/nested: Nested tabs ----------- Tabs can be nested inside one another. .. list-table:: :class: o-showcase-table * - .. tabs:: .. tab:: Stars .. tabs:: .. tab:: The Sun The closest star to us. .. tab:: Proxima Centauri The second closest star to us. .. tab:: Polaris The North Star. .. tab:: Moons .. tabs:: .. tab:: The Moon Orbits the Earth. .. tab:: Titan Orbits Jupiter. * - .. code-block:: text .. tabs:: .. tab:: Stars .. tabs:: .. tab:: The Sun The closest star to us. .. tab:: Proxima Centauri The second closest star to us. .. tab:: Polaris The North Star. .. tab:: Moons .. tabs:: .. tab:: The Moon Orbits the Earth. .. tab:: Titan Orbits Jupiter. .. _contributing/tabs/group: Group tabs ---------- Group tabs are special tabs that synchronize based on a group label. The last selected group is remembered and automatically selected when the user returns to the page or visits another page with the tabs group. The `group-tab` markup is used to define group tabs. .. list-table:: :class: o-showcase-table * - .. tabs:: .. group-tab:: C++ C++ .. group-tab:: Python Python .. group-tab:: Java Java .. tabs:: .. group-tab:: C++ .. code-block:: c++ int main(const int argc, const char **argv) { return 0; } .. group-tab:: Python .. code-block:: python def main(): return .. group-tab:: Java .. code-block:: java class Main { public static void main(String[] args) {} } * - .. code-block:: text .. tabs:: .. group-tab:: C++ C++ .. group-tab:: Python Python .. group-tab:: Java Java .. tabs:: .. group-tab:: C++ .. code-block:: c++ int main(const int argc, const char **argv) { return 0; } .. group-tab:: Python .. code-block:: python def main(): return .. group-tab:: Java .. code-block:: java class Main { public static void main(String[] args) {} } .. _contributing/tabs/code: Code tabs --------- Code tabs are essentially :ref:`group tabs ` that treat the content as a :ref:`code block `. The `code-tab` markup is used to define a code tab. Just as for the `code-block` markup, the language defines the syntax highlighting of the tab. If set, the label is used instead of the language for grouping tabs. .. list-table:: :class: o-showcase-table * - .. tabs:: .. code-tab:: c++ Hello C++ #include int main() { std::cout << "Hello World"; return 0; } .. code-tab:: python Hello Python print("Hello World") .. code-tab:: javascript Hello JavaScript console.log("Hello World"); * - .. code-block:: text .. tabs:: .. code-tab:: c++ Hello C++ #include int main() { std::cout << "Hello World"; return 0; } .. code-tab:: python Hello Python print("Hello World") .. code-tab:: javascript Hello JavaScript console.log("Hello World"); .. _contributing/cards: Cards ===== .. list-table:: :class: o-showcase-table * - .. cards:: .. card:: Documentation :target: ../documentation :tag: Step-by-step guide :large: Use this guide to acquire the tools and knowledge you need to write documentation. .. card:: Content guidelines :target: content_guidelines List of guidelines and trips and tricks to make your content shine at its brightest! .. card:: RST guidelines :target: rst_guidelines List of technical guidelines to observe when writing with reStructuredText. * - .. code-block:: text .. cards:: .. card:: Documentation :target: ../documentation :tag: Step-by-step guide :large: Use this guide to acquire the tools and knowledge you need to write documentation. .. card:: Content guidelines :target: content_guidelines List of guidelines and trips and tricks to make your content shine at its brightest! .. card:: RST guidelines :target: rst_guidelines List of technical guidelines to observe when writing with reStructuredText. .. _contributing/document-metadata: Document metadata ================= | Sphinx supports document-wide metadata markups 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. | +-----------------+--------------------------------------------------------------------------------+ | `show-toc` | Show the table of content on a page that has the `show-content` metadata | | | markup. | +-----------------+--------------------------------------------------------------------------------+ | `code-column` | | Show a dynamic side column that can be used to display interactive | | | tutorials or code excerpts. | | | | For example, see | | | :doc:`/applications/finance/accounting/get_started/cheat_sheet`. | +-----------------+--------------------------------------------------------------------------------+ | `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 `
` element of the document. | +-----------------+--------------------------------------------------------------------------------+ | `orphan` | Suppress the need to include the document in a toctree. | +-----------------+--------------------------------------------------------------------------------+ | `nosearch` | Exclude the document from search results. | +-----------------+--------------------------------------------------------------------------------+ .. _contributing/formatting-tips: Formatting tips =============== .. _contributing/line-break: Break the line but not the paragraph ------------------------------------ .. list-table:: :class: o-showcase-table * - | A first long line that you break in two -> here <- is rendered as a single line. | A second line that follows a line break. * - .. code-block:: text | A first long line that you break in two -> here <- is rendered as a single line. | A second line that follows a line break. .. _contributing/escaping: 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 cases such as :ref:`external hyperlinks `, 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```.