From 1faf5486a7f9bd70feefbb8a86ef40c803354163 Mon Sep 17 00:00:00 2001 From: "keli brugalli (kbr)" Date: Wed, 9 Jun 2021 13:23:55 +0200 Subject: [PATCH 1/3] [IMP] sales: fix typos Fixed a couple of english grammar mistakes in the introduction paragraph. Fixed can be fast-forwaded to 13 and 14 as well. --- content/applications/sales/sales/invoicing/expense.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/applications/sales/sales/invoicing/expense.rst b/content/applications/sales/sales/invoicing/expense.rst index 8a31795eb..53556ebd4 100644 --- a/content/applications/sales/sales/invoicing/expense.rst +++ b/content/applications/sales/sales/invoicing/expense.rst @@ -3,8 +3,8 @@ Re-invoice expenses to customers ================================ It often happens that your employees have to spend their personal money -while working on a project for your client. Let's take the example of an -consultant paying an hotel to work on the site of your client. As a +while working on a project for your client. Let's take the example of a +consultant paying for a hotel to work on the site of your client. As a company, you would like to be able to invoice that expense to your client. From ec1dc7b63293acfa0a1fab407e8e6eadcf896f02 Mon Sep 17 00:00:00 2001 From: "Antoine Vandevenne (anv)" Date: Tue, 8 Jun 2021 15:29:33 +0200 Subject: [PATCH 2/3] [IMP] contributing: list supported metadata directives The opportunity is also take to refresh the section about admonitions and to add undocumented admonitions. task-2534984 --- .../documentation/rst_cheat_sheet.rst | 144 +++++++++++++----- 1 file changed, 108 insertions(+), 36 deletions(-) diff --git a/content/contributing/documentation/rst_cheat_sheet.rst b/content/contributing/documentation/rst_cheat_sheet.rst index 9b2905157..e9a7868ff 100644 --- a/content/contributing/documentation/rst_cheat_sheet.rst +++ b/content/contributing/documentation/rst_cheat_sheet.rst @@ -14,28 +14,31 @@ Headings 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 | | ``=======`` | 1/1 | -| | | ``Heading`` | | -| | | ``=======`` | | -+--------------+---------------+-------------------------------+ -| H2 | | ``Heading`` | 0/∞ | -| | | ``=======`` | | -+--------------+---------------+-------------------------------+ -| H3 | | ``Heading`` | 0/∞ | -| | | ``-------`` | | -+--------------+---------------+-------------------------------+ -| H4 | | ``Heading`` | 0/∞ | -| | | ``~~~~~~~`` | | -+--------------+---------------+-------------------------------+ -| H5 | | ``Heading`` | 0/∞ | -| | | ``*******`` | | -+--------------+---------------+-------------------------------+ -| H6 | | ``Heading`` | 0/∞ | -| | | ``^^^^^^^`` | | -+--------------+---------------+-------------------------------+ ++--------------+---------------+ +| Heading size | Formatting | ++==============+===============+ +| H1 | | ``=======`` | +| | | ``Heading`` | +| | | ``=======`` | ++--------------+---------------+ +| H2 | | ``Heading`` | +| | | ``=======`` | ++--------------+---------------+ +| H3 | | ``Heading`` | +| | | ``-------`` | ++--------------+---------------+ +| H4 | | ``Heading`` | +| | | ``~~~~~~~`` | ++--------------+---------------+ +| H5 | | ``Heading`` | +| | | ``*******`` | ++--------------+---------------+ +| H6 | | ``Heading`` | +| | | ``^^^^^^^`` | ++--------------+---------------+ + +.. important:: + Each document must have **exactly one H1 heading**. No less, no more. .. _contributing/markup: @@ -373,13 +376,13 @@ RST .. code-block:: rst .. note:: - Use this to get the attention of the reader about additional information. + Use this admonition to grab the reader's attention about additional information. Render ~~~~~~ .. note:: - Use this to get the attention of the reader about additional information. + Use this admonition to grab the reader's attention about additional information. .. _contributing/tip: @@ -392,15 +395,32 @@ RST .. code-block:: rst .. tip:: - Use this 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. Render ~~~~~~ .. tip:: - Use this 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. + +.. _contributing/exercise: + +Exercise +-------- + +RST +~~~ + +.. code-block:: rst + + .. exercise:: + Use this admonition to suggest an exercise to the reader. + +Render +~~~~~~ + +.. exercise:: + Use this admonition to suggest an exercise to the reader. .. _contributing/important: @@ -413,13 +433,13 @@ RST .. code-block:: rst .. important:: - Use this to notify the reader about an important information. + Use this admonition to notify the reader about an important information. Render ~~~~~~ .. important:: - Use this to notify the reader about an important information. + Use this admonition to notify the reader about an important information. .. _contributing/warning: @@ -432,15 +452,15 @@ RST .. code-block:: rst .. warning:: - Use this 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. Render ~~~~~~ .. warning:: - Use this 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. .. _contributing/danger: @@ -453,13 +473,65 @@ RST .. code-block:: rst .. danger:: - Use this to alarm the reader about a serious threat. + Use this admonition to bring the reader's attention to a serious threat. Render ~~~~~~ .. danger:: - Use this to alarm the reader about a serious threat. + Use this admonition to bring the reader's attention to a serious threat. + +.. _contributing/custom-admonition: + +Custom +------ + +RST +~~~ + +.. code-block:: rst + + .. admonition:: Title + + Customize this admonition with a **Title** of your choice. + +Render +~~~~~~ + +.. admonition:: Title + + Customize this admonition with a **Title** of your choice. + +.. _contributing/document-metadata: + +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. | +| | | For example, see :doc:`/developer/webservices/upgrade` or | +| | :doc:`/applications/finance/accounting/overview/main_concepts/memento`. | ++-----------------+--------------------------------------------------------------------------------+ +| `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: From 23a40f9748b47291826da292c06524047d70ea62 Mon Sep 17 00:00:00 2001 From: "Antoine Vandevenne (anv)" Date: Tue, 8 Jun 2021 17:15:08 +0200 Subject: [PATCH 3/3] [IMP] contributing: encourage flat pages hierarchy task-2563614 --- .../documentation/content_guidelines.rst | 42 ++++++++++++++----- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/content/contributing/documentation/content_guidelines.rst b/content/contributing/documentation/content_guidelines.rst index db606ff91..3d81dbc04 100644 --- a/content/contributing/documentation/content_guidelines.rst +++ b/content/contributing/documentation/content_guidelines.rst @@ -7,9 +7,9 @@ tricks that will make your content shine at its brightest! While we encourage yo writing style, some rules still apply to give the reader more clarity and comprehension. .. note:: - We strongly recommend contributors to carefully read the other documents in this *Contribution* - section of the documentation. Good knowledge of the ins and outs of **RST writing** is required - to write and submit your contribution. Note that it also affects your writing style itself. + We strongly recommend contributors to carefully read the other documents related to this section + of the documentation. Good knowledge of the ins and outs of **RST writing** is required to write + and submit your contribution. Note that it also affects your writing style itself. - :doc:`../documentation` - :doc:`rst_cheat_sheet` @@ -89,7 +89,7 @@ To write good titles and headings: | | Examples | Explanations | +==================+===================================+========================================================+ | | **Titles** | *Quotation Templates* | "Quotation Templates" is a feature in Odoo. | -| | (h1) +-----------------------------------+--------------------------------------------------------+ +| | (H1) +-----------------------------------+--------------------------------------------------------+ | | *Lead Mining* | "Lead Mining" is a feature in Odoo. | | +-----------------------------------+--------------------------------------------------------+ | | *Resupply from another Warehouse* | "Warehouse" is capitalized as we refer to the feature | @@ -99,7 +99,7 @@ To write good titles and headings: | | with Odoo* | | +------------------+-----------------------------------+--------------------------------------------------------+ | | **Headings** | *Confirm the quotation* | "The quotation" is a common noun not referring to a | -| | (h2, h3, etc.) | | feature in Odoo. | +| | (H2, H3, etc.) | | feature in Odoo. | | +-----------------------------------+--------------------------------------------------------+ | | *Test environment* | "Environment" is a common noun. | | +-----------------------------------+--------------------------------------------------------+ @@ -111,16 +111,17 @@ To write good titles and headings: .. _contributing/document-structure: -Document's structure -==================== +Document structure +================== -Use different **headings levels** to organize your text by sections and sub-sections. Your headings -are also displayed in a dynamic *navigation bar* on the side. +Use different **heading levels** to organize your text by sections and sub-sections. Your headings +are not only displayed in the document but also on the navigation menu (only the H1) and on the +"On this page" sidebar (all H2 to H6). +---------------------------------------------------------------------------------------+ | | **H1: Page title** | | | Your *page title* gives your reader a quick and clear understanding of what your | -| content is about. It is also referenced in the section's *table of contents*. | +| content is about. | | | | The *content* in this section describes the upcoming content from a **business point | | of view**, and shouldn't put the emphasis on Odoo, as this is documentation and not | @@ -154,6 +155,27 @@ are also displayed in a dynamic *navigation bar* on the side. - :ref:`RST cheat sheet: headings ` - :ref:`RST cheat sheet: specialized directives ` +.. _contributing/organizing-documentation: + +Organizing the documentation +============================ + +When writing documentation about a given topic, try to keep pages within the same folder organized. + +For most topics, a single page should do the job. Place it in the appropriate section of the +documentation (e.g., content related to the CRM app go under :menuselection:`Applications +-> Sales -> CRM`) and follow the :ref:`document structure ` +guidelines. + +For more complex topics, you may need several pages to cover all their aspects. Usually, you will +find yourself adding documentation to a topic that is already partially covered. In that case, +either create a new page and place it at the same level as other related pages or add new sections +to an existing page. If you are documenting a complex topic from scratch, organize your content +between one parent page (the :abbr:`TOC (Tree Of Contents)` page) and several child pages. Whenever +possible, write content on the parent page and not only on the child pages. Make the parent page +accessible from the navigation menu by using the :ref:`show-content +` metadata directive. + .. _contributing/content-images: Images