diff --git a/content/contributing/check_mergeability_status.rst b/content/contributing/check_mergeability_status.rst deleted file mode 100644 index 1b01b336b..000000000 --- a/content/contributing/check_mergeability_status.rst +++ /dev/null @@ -1 +0,0 @@ -At the bottom of the page, check the mergeability status and address any issues. diff --git a/content/contributing/configure_git_authorship.rst b/content/contributing/configure_git_authorship.rst deleted file mode 100644 index efae7cba9..000000000 --- a/content/contributing/configure_git_authorship.rst +++ /dev/null @@ -1,7 +0,0 @@ -Configure Git to identify yourself as the author of your future contributions. Enter the same email -address you used to register on GitHub. - -.. code-block:: console - - $ git config --global user.name "Your Name" - $ git config --global user.email "youremail@example.com" diff --git a/content/contributing/configure_github_account.rst b/content/contributing/configure_github_account.rst deleted file mode 100644 index 965b28cae..000000000 --- a/content/contributing/configure_github_account.rst +++ /dev/null @@ -1,2 +0,0 @@ -`Generate a new SSH key and register it on your GitHub account -`_. diff --git a/content/contributing/create_github_account.rst b/content/contributing/create_github_account.rst deleted file mode 100644 index ad8352474..000000000 --- a/content/contributing/create_github_account.rst +++ /dev/null @@ -1,3 +0,0 @@ -First, you need to `create a GitHub account `_. Odoo uses GitHub to manage -the source code of its products, and this is where you will make your changes and submit them for -review. diff --git a/content/contributing/development.rst b/content/contributing/development.rst index 9e6c9a729..3bfc16993 100644 --- a/content/contributing/development.rst +++ b/content/contributing/development.rst @@ -28,15 +28,25 @@ The instructions below help you prepare your environment for making local change and then push them to GitHub. Skip this section and go to :ref:`contributing/development/first-contribution` if you have already completed this step. -#. .. include:: create_github_account.rst -#. .. include:: configure_github_account.rst +#. First, you need to `create a GitHub account `_. Odoo uses GitHub to + manage the source code of its products, and this is where you will make your changes and submit + them for review. +#. `Generate a new SSH key and register it on your GitHub account + `_. #. Go to `github.com/odoo/odoo `_ and click on the :guilabel:`Fork` button in the top right corner to create a fork (:dfn:`your own copy`) of the repository on your account. Do the same with `github.com/odoo/enterprise `_ if you have access to it. This creates a copy of the codebase to which you can make changes without affecting the main codebase. Skip this step if you work at Odoo. #. .. include:: install_git.rst -#. .. include:: configure_git_authorship.rst +#. Configure Git to identify yourself as the author of your future contributions. Enter the same + email address you used to register on GitHub. + + .. code-block:: console + + $ git config --global user.name "Your Name" + $ git config --global user.email "youremail@example.com" + #. :doc:`Install Odoo from the sources <../administration/on_premise/source>`. Make sure to fetch the sources through Git with SSH. #. Configure Git to push changes to your fork(s) rather than to the main codebase. If you work at @@ -155,7 +165,10 @@ navigate to the directory where you installed Odoo from sources and follow the g #. Tick the :guilabel:`Allow edits from maintainer` checkbox. Skip this step if you work at Odoo. #. Complete the description and click on the :guilabel:`Create pull request` button again. -#. .. include:: check_mergeability_status.rst -#. .. include:: handle_reviews.rst +#. At the bottom of the page, check the mergeability status and address any issues. +#. As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team + is automatically assigned for review. If the reviewer has questions or remarks, they will + post them as comments and you will be notified by email. Those comments must be resolved + for the contribution to go forward. #. Once your changes are approved, the review merges them and they become available for all Odoo users after the next code update! diff --git a/content/contributing/documentation.rst b/content/contributing/documentation.rst index 86978fd77..1690ffada 100644 --- a/content/contributing/documentation.rst +++ b/content/contributing/documentation.rst @@ -8,29 +8,26 @@ Documentation :titlesonly: documentation/content_guidelines - documentation/rst_cheat_sheet documentation/rst_guidelines -This introductory guide will help you acquire the tools and knowledge you need to write -documentation, whether you plan to make a minor content change or document an application from -scratch. +This introductory guide will help you acquire the tools and knowledge needed to contribute to the +documentation. + +Read the :ref:`introduction to the reStructuredText language ` +if you are not familiar with it. Then, there are two courses of action to start contributing to the +documentation: + +- **For minor changes**, such as adding a paragraph or fixing a typo, we recommend **using the + GitHub interface**. This is the easiest and fastest way to submit changes, and it is suitable for + non-technical people. Jump directly to the :ref:`contributing/documentation/first-contribution` + section to get started. +- **For more complex changes**, such as adding a new page, it is necessary to **use Git** and work + from a local copy of the documentation. Follow the instructions in the + :ref:`contributing/documentation/setup` section first to prepare your environment. .. seealso:: :doc:`Discover other ways to contribute to Odoo <../contributing>` -Read the :ref:`introduction to the reStructuredText language ` -if you are not familiar with it. Then, you have two courses of action to start contributing to the -documentation, depending on whether you want to propose minor changes to existing content or you -instead want to work on significant changes to new and existing content. - -- **For minor changes**, for example, adding a paragraph or fixing a typo, we recommend **using the - GitHub interface**. This is the easiest and fastest way to submit your changes, and it is suitable - for non-technical people. Jump directly to the - :ref:`contributing/documentation/first-contribution` section to get started. -- **For more complex changes**, it is necessary to **use Git** and work from a local copy of the - documentation. Follow the instructions in the :ref:`contributing/documentation/setup` section to - first prepare your environment. - .. _contributing/documentation/rst-intro: reStructuredText (RST) @@ -38,24 +35,13 @@ reStructuredText (RST) The documentation is written in **reStructuredText** (RST), a `lightweight markup language `_ consisting of regular text augmented -with markup, which allows including headings, images, notes, and so on. This might seem a bit -abstract, but there is no need to worry; :abbr:`RST (reStructuredText)` is not hard to learn, -especially if you intend to make minor changes to the content. - -If you need to learn about a specific markup, head over to our :doc:`cheat sheet for RST -`; it contains all the information you should ever need for the -documentation of Odoo. +with markup, which allows including headings, images, notes, and so on. :abbr:`RST +(reStructuredText)` is easy to use, even if you are not familiar with it. .. important:: - We kindly ask you to observe a set of :doc:`content ` and + Be mindful of our :doc:`content ` and :doc:`RST ` guidelines as you write documentation. This ensures - that you stay consistent with the rest of the documentation and facilitates the approval of your - content changes as the Odoo team reviews them. - -.. seealso:: - - :doc:`documentation/content_guidelines` - - :doc:`documentation/rst_cheat_sheet` - - :doc:`documentation/rst_guidelines` + that the documentation stays consistent and facilitates the approval of changes by the Odoo team. .. _contributing/documentation/setup: @@ -67,14 +53,23 @@ documentation and then push them to GitHub. Skip this section and go to :ref:`contributing/documentation/first-contribution` if you have already completed this step or want to make changes from the GitHub interface. -#. .. include:: create_github_account.rst -#. .. include:: configure_github_account.rst +#. First, `create a GitHub account `_. Odoo uses GitHub to manage the + source code of its products, and this is where you will submit your changes. +#. `Generate a new SSH key and register it on your GitHub account + `_. #. Go to `github.com/odoo/documentation `_ and click on the :guilabel:`Fork` button in the top right corner to create a fork (:dfn:`your own copy`) of the repository on your account. This creates a copy of the codebase to which you can make changes without affecting the main codebase. Skip this step if you work at Odoo. #. .. include:: install_git.rst -#. .. include:: configure_git_authorship.rst +#. Configure Git to identify yourself as the author of your future contributions. Enter the same + email address you used to register on GitHub. + + .. code-block:: console + + $ git config --global user.name "Your Name" + $ git config --global user.email "youremail@example.com" + #. Clone the sources with Git and navigate into the local repository. .. code-block:: console @@ -109,7 +104,7 @@ to make changes from the GitHub interface. $ git config commit.template %CD%\commit_template.txt #. Install the latest release of `Python `_ - and `pip `_ on your machine. + and `pip `_. #. Install the Python dependencies of the documentation with pip. .. code-block:: console @@ -149,18 +144,20 @@ to make changes from the GitHub interface. `_. #. `Install pngquant `_. -#. That's it! You are ready to :ref:`make your first contribution +#. You are now ready to :ref:`make your first contribution ` with Git. .. _contributing/documentation/first-contribution: -Make your first contribution -============================ +Contributing to the documentation +================================= .. tabs:: .. tab:: Contribute from the GitHub interface - #. .. include:: create_github_account.rst + + #. First, `create a GitHub account `_. Odoo uses GitHub to manage the + source code of its products, and this is where you will submit your changes. #. Verify that you are browsing the documentation in the version that you intend to change. The version can be selected from the dropdown in the top menu. #. Head to the page that you want to change and click on the :guilabel:`Edit on GitHub` button @@ -194,9 +191,14 @@ Make your first contribution Odoo. #. Review the summary that you wrote about your changes and click on the :guilabel:`Create pull request` button again. - #. .. include:: check_mergeability_status.rst - #. .. include:: handle_reviews.rst - #. .. include:: documentation/changes_approved.rst + #. At the bottom of the page, check the mergeability status and address any issues. + #. As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team + is automatically assigned for review. If the reviewer has questions or remarks, they will + post them as comments and you will be notified by email. Those comments must be resolved + for the contribution to go forward. + + #. Once your changes are approved, the reviewer merges them and they appear online the next + day. .. tab:: Contribute with Git @@ -230,7 +232,7 @@ Make your first contribution #. Make the desired changes while taking care of following the :doc:`content ` and :doc:`RST ` guidelines. - #. Compress all PNG images that you added or modified. + #. Compress all PNG images that were added or modified. .. code-block:: console @@ -239,9 +241,9 @@ Make your first contribution #. Write a `redirect rule `_ for every RST - file that your renamed. - #. Build the documentation with :command:`make`. Then, open :file:`_build/index.html` in your - web browser to browse the documentation with your changes. + file that were renamed. + #. Build the documentation with :command:`make`. Then, open :file:`_build/index.html` in a web + browser to browse the documentation with your changes. .. tip:: Use :command:`make help` to learn about other useful commands. @@ -254,7 +256,7 @@ Make your first contribution $ git add . $ git commit - #. Push your change to your fork, for which we added the remote alias `dev`. + #. Push your changes to your fork, for which we added the remote alias `dev`. .. example:: @@ -285,6 +287,10 @@ Make your first contribution Odoo. #. Complete the description and click on the :guilabel:`Create pull request` button again. - #. .. include:: check_mergeability_status.rst - #. .. include:: handle_reviews.rst - #. .. include:: documentation/changes_approved.rst + #. At the bottom of the page, check the mergeability status and address any issues. + #. As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team + is automatically assigned for review. If the reviewer has questions or remarks, they will + post them as comments and you will be notified by email. Those comments must be resolved + for the contribution to go forward. + #. Once your changes are approved, the reviewer merges them and they appear online the next + day. diff --git a/content/contributing/documentation/changes_approved.rst b/content/contributing/documentation/changes_approved.rst deleted file mode 100644 index 6e060a302..000000000 --- a/content/contributing/documentation/changes_approved.rst +++ /dev/null @@ -1 +0,0 @@ -Once your changes are approved, the reviewer merges them and they appear online the next day! diff --git a/content/contributing/documentation/content_guidelines.rst b/content/contributing/documentation/content_guidelines.rst index 043c20a3c..7438e5b46 100644 --- a/content/contributing/documentation/content_guidelines.rst +++ b/content/contributing/documentation/content_guidelines.rst @@ -2,228 +2,294 @@ Content guidelines ================== -To give the community the best documentation possible, we listed here a few guidelines, tips and -tricks that will make your content shine at its brightest! While we encourage you to adopt your own -writing style, some rules still apply to give the reader more clarity and comprehension. +While we encourage you to adopt your own writing style, some rules still apply to maintain clarity +and ensure readers can easily understand the content. + +.. important:: + We strongly recommend to read the :doc:`rst_guidelines` and the main :doc:`../documentation` + pages before contributing. + +.. _contributing/content/organization: + +Documentation organization +========================== + +When writing documentation about a given topic, 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 goes under :menuselection:`User Docs --> Sales +--> CRM`) and follow the :ref:`document structure ` guidelines. + +For more complex topics, several pages may be needed 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. When documenting a complex topic from scratch, organize the content across +several child pages that are referenced on that directory's parent page (the :abbr:`TOC (Table Of +Contents)` page); 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. .. note:: - 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. + Avoid duplicating content whenever possible; if a topic is already documented on another page, + :ref:`reference ` that existing information instead of repeating it. - - :doc:`../documentation` - - :doc:`rst_cheat_sheet` - - :doc:`rst_guidelines` +.. important:: + When deleting or moving a `.rst` file, update the corresponding text file in the + :file:`redirects` folder based on your branch's version (e.g., :file:`17.0.txt`). To do so, add a + new line at the bottom of the relevant section (e.g., `# applications/sales`). On this line, + first, add the redirection entry point with the old file location, followed by a space, and then + add the exit point with the new or relevant file location. For example, if moving the file + :file:`unsplash.rst` from :file:`applications/websites/website/configuration` to + :file:`applications/general/integrations`, add the following entry under the section + `# applications/websites`: -.. _contributing/writing-style: + .. code-block:: text + + applications/websites/website/configuration/unsplash.rst applications/general/integrations/unsplash.rst + +.. _contributing/content/structure: + +Document structure +================== + +Use different **heading levels** to organize text by sections and sub-sections. 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** | +| | The *page title* gives readers a quick and clear understanding of what the content | +| is about. | +| | +| The *content* in this section describes the upcoming content from a **business point | +| of view**, and should not put the emphasis on Odoo, as this is documentation and not | +| marketing. | +| | +| Under the page title (H1), start with a **lead paragraph**, which helps the reader | +| make sure that they've found the right page, then explain the **business aspects of | +| this topic** in the following paragraphs. | ++-----+---------------------------------------------------------------------------------+ +| | | **H2: Section title (configuration)** | +| | | This first H2 section is about the configuration of the feature, or the | +| | prerequisites to achieve a specific goal. | ++-----+---------------------------------------------------------------------------------+ +| | | **H2: Section title (main sections)** | +| | | Create as many main sections as you have actions or features to distinguish. | ++-----+-----+---------------------------------------------------------------------------+ +| | | | **H3: Subsection** | +| | | | Subsections are perfect for assessing very specific points. | ++-----+-----+---------------------------------------------------------------------------+ +| | **H2: Next Section** | ++-----+---------------------------------------------------------------------------------+ + +To write good titles and headings: + +- **Be concise**: **avoid sentences**, questions, and titles starting with "how to". +- **Do not use pronouns** in your titles, especially 2nd person (*you/your*). +- Use **sentence case**. This means you capitalize only: + + - the first word of the title or heading; + - the first word after a colon; + - proper nouns (brands, product and service names, etc.). + +.. note:: + - Most titles and headings generally refer to a concept and do *not* represent the name of a + feature or a model. + - Do not capitalize the words of an acronym if they do not entail a proper noun. + - Verbs in headings are fine since they often describe an action. + +.. seealso:: + - :ref:`RST cheat sheet: headings ` + - :ref:`RST cheat sheet: markups ` + +.. _contributing/content/writing-style: Writing style ============= -**Writing for documentation** isn't the same as writing for a blog or another medium. Readers are -more likely to skim read until they've found the information they are looking for. Keep in mind that -the user documentation is a place to inform and describe, not to convince and promote. +Writing for documentation is not the same as writing for a blog or another medium. Readers are +more likely to skim through content to find the information they need. Keep in mind that the +documentation is a place to **inform and describe**, not to convince and promote. -.. _contributing/consistency: +.. tip:: + Avoid using *you* as much as possible by opting for the imperative mood where appropriate. + However, do not complicate sentences just to avoid addressing the reader directly. + + .. example:: + | **Good example:** + | Select the appropriate option from the dropdown menu. + + | **Bad example:** + | You can select the appropriate option from the dropdown menu. + +.. _contributing/content/spelling: + +Spelling +-------- + +Use American English spelling and grammar throughout the documentation. + +.. _contributing/content/consistency: Consistency ----------- *Consistency is key to everything.* -Make sure that your writing style remains **consistent**. If you modify an existing text, try to -match the existing tone and presentation, or rewrite it to match your own style. +Make sure that the writing style remains **consistent**. When modifying existing content, try to +match the existing tone and presentation or rewrite it to match your own style. -.. _contributing/grammatical-tenses: +.. _contributing/content/capitalization: + +Capitalization +-------------- + +- Use sentence case in :ref:`titles `. +- Capitalize app names, e.g., **Odoo Sales**, the **Sales** app, etc. +- Capitalize labels (such as fields and buttons) as they appear in Odoo. If a label is in all caps, + convert it to sentence case. +- Capitalize the first letter after a colon if it is a complete sentence. +- Avoid capitalizing common nouns, such as "sales order" and "bill of materials", unless you + reference a label or a model. + +.. _contributing/content/grammatical-tenses: Grammatical tenses ------------------ -In English, descriptions and instructions require the use of a **Present Tense**, while a *future -tense* is appropriate only when a specific event is to happen ulteriorly. This logic might be -different in other languages. - -- | Good example (present): - | *Screenshots are automatically resized to fit the content block's width.* -- | Bad example (future): - | *When you take a screenshot, remember that it will be automatically resized to fit the content - block's width.* - -.. _contributing/paragraphing: - -Paragraphing ------------- - -A paragraph comprises several sentences that are linked by a shared idea. They usually are two to -six lines long. - -In English, a new idea implies a new paragraph, rather than having a *line break* as it is common to -do in some other languages. *Line breaks* are useful for layout purposes but shouldn't be used as a -grammatical way of separating ideas. - -.. seealso:: - - :ref:`RST cheat sheet: Break the line but not the paragraph ` - -.. _contributing/titles: - -Titles and headings -------------------- - -To write good titles and headings: - -- **Be concise.** - - - **Avoid sentences**, unnecessary verbs, questions, and titles starting with "how to." - -- **Don't use pronouns** in your titles, especially 2nd person (*your*). -- Use **sentence case**. This means you capitalize only: - - - the first word of the title or heading - - the first word after a colon - - proper nouns (brands, product and service names, etc.) - -.. note:: - - Most titles and headings generally refer to a concept and do *not* represent the name of a - feature or a model. - - Do not capitalize the words of an acronym if they don't entail a proper noun. - - Verbs in headings are fine since they often describe an action. +In English, descriptions and instructions usually require the use of the **present tense**, while +the *future tense* is appropriate only when a specific event is to happen ulteriorly. .. example:: - - **Titles** (H1) - - Quotation templates - - Lead mining - - Resupply from another warehouse - - Synchronize Google Calendar with Odoo - - Batch payments: SEPA Direct Debit (SDD) - - Digitize vendor bills with optical character recognition (OCR) + | **Good example (present):** + | Screenshots are automatically resized to fit the content block's width. - - **Headings** (H2, H3) + | **Bad example (future):** + | When you take a screenshot, remember that it will be automatically resized to fit the content + block's width. - - Project stages - - Email alias - - Confirm the quotation - - Generate SEPA Direct Debit XML files to submit payments +.. _contributing/content/lists: -.. _contributing/document-structure: +Lists +===== -Document structure -================== +Lists help organize information in a clear and concise manner and improve readability. They are +used to highlight important details, guide the reader through steps in a systematic way, etc. -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). +Use numbered lists when the sequence matters, e.g., instructions, procedures, or steps that must be +performed in a particular order. -+---------------------------------------------------------------------------------------+ -| | **H1: Page title** | -| | Your *page title* gives your reader a quick and clear understanding of what your | -| 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 | -| marketing. | -| | -| Start first with a **lead paragraph**, which helps the reader make sure that they've | -| found the right page, then explain the **business aspects of this topic** in the | -| following paragraphs. | -+-----+---------------------------------------------------------------------------------+ -| | | **H2: Section title (configuration)** | -| | | This first H2 section is about the configuration of the feature, or the | -| | prerequisites to achieve a specific goal. To add a path, make sure you | -| | use the ``:menuselection:`` specialized directive (see link below). | -| | | -| | | Example: | -| | | To do so, go to ``:menuselection:`App name --> Menu --> Sub-menu```, and | -| | enable the XYZ feature. | -+-----+---------------------------------------------------------------------------------+ -| | | **H2: Section title (main sections)** | -| | | Create as many main sections as you have actions or features to distinguish. | -| | The title can start with a verb, but try to avoid using "Create ...". | -+-----+-----+---------------------------------------------------------------------------+ -| | | | **H3: Subsection** | -| | | | Subsections are perfect for assessing very specific points. The title | -| | | can be in the form of a question, if appropriate. | -+-----+-----+---------------------------------------------------------------------------+ -| | **H2: Next Section** | -+-----+---------------------------------------------------------------------------------+ +Use bulleted lists when the sequence of items does not matter, e.g., lists of features, fields, +options, etc. + +.. tip:: + - Use inline text for explanations or when there are three or fewer list items. + - Combine bulleted and numbered lists using :ref:`nested lists ` + where appropriate. + - Consider grouping simple steps within the same list item, e.g.: Go to :menuselection:`Website + --> Site --> Pages` and click :guilabel:`New`. + - Only use a period at the end of the list item if it forms a complete sentence. + +.. example:: + **Bulleted list** + + The following fields are available on the :guilabel:`Replenishment` report: + + - :guilabel:`Product`: the product that requires a replenishment + - :guilabel:`Location`: the specific location where the product is stored + - :guilabel:`Warehouse`: the warehouse where the product is stored + - :guilabel:`On Hand`: the amount of product currently available + + **Numbered list** + + To create a new website page, proceed as follows: + + #. - Either open the **Website** app, click :guilabel:`+ New` in the top-right corner, then + select :guilabel:`Page`; + - Or go to :menuselection:`Website --> Site --> Pages` and click :guilabel:`New`. + + #. Enter a :guilabel:`Page Title`; this title is used in the menu and the page's URL. + #. Click :guilabel:`Create`. + #. Customize the page's content and appearance using the website builder, then click + :guilabel:`Save`. .. seealso:: - - :ref:`RST cheat sheet: headings ` - - :ref:`RST cheat sheet: markups ` + :ref:`RST cheat sheet: lists ` -.. _contributing/organizing-documentation: +Icons +===== -Organizing the documentation -============================ +Use :ref:`icons ` in instructions to help readers identify user interface +elements and reduce the need for lengthy explanations. Accompany every icon with a descriptor +in brackets. -When writing documentation about a given topic, try to keep pages within the same folder organized. +.. example:: + Once the developer mode is activated, the developer tools can be accessed by clicking the + :icon:`fa-bug` (:guilabel:`bug`) icon. -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. +.. seealso:: + :ref:`RST cheat sheet: icons ` -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: +.. _contributing/content/images: Images ====== -Adding a few images to illustrate your text helps the readers to understand and memorize your -content. However, avoid adding too many images: it isn't necessary to illustrate all steps and -features, and it may overload your page. +Adding a few images to illustrate text helps the readers understand and memorize the content. +However, images should never replace text: written instructions should be complete and clear on +their own, without relying on visual aids. Use images sparingly, for example, to highlight a +particular point or clarify an example. .. important:: - Don't forget to :ref:`compress your PNG files with pngquant - `. + Do not forget to `compress your PNG files with pngquant `_. -.. _contributing/screenshots: +.. _contributing/content/screenshots: Screenshots ----------- -Screenshots are automatically resized to fit the content block's width. This implies that -screenshots can't be too wide, else they would appear very small on-screen. Therefore, we recommend -to avoid to take screenshots of a full screen display of the app, unless it is relevant to do so. +Screenshots are automatically resized to fit the content block's width. This implies that if they +are too wide, they are not readable on lower-resolution screens. We recommend avoiding full-screen +screenshots of the app unless absolutely necessary and making sure images are no wider than a range +of 768-933 pixels. -A few tips to improve your screenshots: +Here are a few tips to improve your screenshots: -#. **Zoom** in your browser. We recommend a 110% zoom for better results. #. **Resize** your browser's width, either by *resizing the window* itself or by opening the - *browser's developer tools* (press the ``F12`` key) and resizing the width. -#. **Select** the relevant area, rather than keeping the full window. -#. If necessary, you can **edit** the screenshot to remove unnecessary fields and to narrow even - more Odoo's display. + *browser's developer tools* and resizing the width. +#. **Select** the relevant area rather than keeping the entire window. +#. **Remove** unnecessary information and **resize** columns when applicable. -.. image:: content_guidelines/screenshot-tips.gif - :align: center - :alt: Three tips to take good screenshots for the Odoo documentation. +.. important:: + Do not use markups such as rectangles or arrows on screenshots. Instead, crop the image to + highlight the most relevant information, and ensure that text instructions are clear and + self-explanatory without relying on images. -.. note:: - Resizing the window's width is the most important step to do as Odoo's responsive design - automatically resizes all fields to match the window's width. +.. example:: + **Good example (resized browser, no unnecessary columns, adjusted columns' width, cropped):** -.. _contributing/media-files: + .. image:: content_guidelines/quotations-list-reduced.png + :alt: Cropped screenshot + + **Bad example (full-width screenshot):** + + .. image:: content_guidelines/quotations-list-full.png + :alt: Full-width screenshot + +.. _contributing/content/media-files: Media files ----------- A **media filename**: -- is written in **lower-case letters** -- is **relevant** to the media's content. (E.g., :file:`screenshot-tips.gif`.) -- separates its words with a **hyphen** ``-`` (E.g., :file:`awesome-filename.png`.) +- is written in **lower-case letters**; +- is **relevant** to the media's content. (e.g., :file:`screenshot-tips.gif`); +- separates its words with a **hyphen** `-` (e.g., :file:`awesome-filename.png`). -Each document has its own folder in which the media files are located. The folder's name must be the -same as the document's filename. +Each RST file has its own folder for storing media files. The folder's name must be the same as the +RST file's name. For example, the document :file:`doc_filename.rst` refers to two images that are placed in the folder ``doc_filename``. @@ -238,12 +304,12 @@ folder ``doc_filename``. .. note:: Previously, image filenames would mostly be named with numbers (e.g., :file:`feature01.png`) and - placed in a single ``media`` folder. While it is advised not to name your *new* images in that - fashion, it is also essential **not to rename unchanged files**, as doing this would double the - weight of renamed image files on the repository. They will eventually all be replaced as the + placed in a single :file:`media` folder. While it is advised not to name your *new* images in + that fashion, it is also essential **not to rename unchanged files**, as doing this would double + the weight of renamed image files on the repository. They will eventually all be replaced as the content referencing those images is updated. -.. _contributing/alt-tags: +.. _contributing/content/alt-tags: ALT tags -------- @@ -251,14 +317,22 @@ ALT tags An **ALT tag** is a *text alternative* to an image. This text is displayed if the browser fails to render the image. It is also helpful for users who are visually impaired. Finally, it helps search engines, such as Google, to understand what the image is about and index it correctly, which -improves the :abbr:`SEO (Search Engine Optimization)` significantly. +improves :abbr:`SEO (Search Engine Optimization)`. Good ALT tags are: -- **Short** (one line maximum) -- **Not a repetition** of a previous sentence or title -- A **good description** of the action happening on the image -- Easily **understandable** if read aloud +- **Short** (one line maximum); +- **Not a repetition** of a previous sentence or title; +- A **good description** of the action happening in the image; +- Easily **understandable** if read aloud. + +.. example:: + + An appropriate ALT tag for the following screenshot would be *Activating the developer mode in + the Settings app*. + + .. image:: content_guidelines/settings.png + :alt: Activating the developer mode in the Settings app .. seealso:: - - :ref:`RST cheat sheet: image directive ` + :ref:`RST cheat sheet: images ` diff --git a/content/contributing/documentation/content_guidelines/quotations-list-full.png b/content/contributing/documentation/content_guidelines/quotations-list-full.png new file mode 100644 index 000000000..188587682 Binary files /dev/null and b/content/contributing/documentation/content_guidelines/quotations-list-full.png differ diff --git a/content/contributing/documentation/content_guidelines/quotations-list-reduced.png b/content/contributing/documentation/content_guidelines/quotations-list-reduced.png new file mode 100644 index 000000000..b750df64e Binary files /dev/null and b/content/contributing/documentation/content_guidelines/quotations-list-reduced.png differ diff --git a/content/contributing/documentation/content_guidelines/screenshot-tips.gif b/content/contributing/documentation/content_guidelines/screenshot-tips.gif deleted file mode 100644 index c113e2daa..000000000 Binary files a/content/contributing/documentation/content_guidelines/screenshot-tips.gif and /dev/null differ diff --git a/content/contributing/documentation/content_guidelines/settings.png b/content/contributing/documentation/content_guidelines/settings.png new file mode 100644 index 000000000..5d43936c7 Binary files /dev/null and b/content/contributing/documentation/content_guidelines/settings.png differ diff --git a/content/contributing/documentation/rst_cheat_sheet.rst b/content/contributing/documentation/rst_cheat_sheet.rst deleted file mode 100644 index 779f140a4..000000000 --- a/content/contributing/documentation/rst_cheat_sheet.rst +++ /dev/null @@ -1,1146 +0,0 @@ -: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```. diff --git a/content/contributing/documentation/rst_cheat_sheet/create-invoice.png b/content/contributing/documentation/rst_cheat_sheet/create-invoice.png deleted file mode 100644 index b02b2c288..000000000 Binary files a/content/contributing/documentation/rst_cheat_sheet/create-invoice.png and /dev/null differ diff --git a/content/contributing/documentation/rst_guidelines.rst b/content/contributing/documentation/rst_guidelines.rst index 08de01f55..36edacf49 100644 --- a/content/contributing/documentation/rst_guidelines.rst +++ b/content/contributing/documentation/rst_guidelines.rst @@ -1,162 +1,1369 @@ -============== -RST guidelines -============== +:custom-css: showcase_tables.css -.. _contributing/relative-links: - -Use relative links for internal URLs -==================================== - -If you need to reference an internal documentation page or a file that is not sitting in the same -directory as your current page, always make use of *relative file paths* rather than *absolute file -paths*. An absolute file path indicates the location of the target from the root of its file tree. A -relative file path makes use of smart notations (such as ``../`` that redirects to the parent -folder) to indicate the location of the target *relative* to that of the source document. - -Example -------- - -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 :file:`prices.html` and :file:`variants.html` could be made from -:file:`import.rst` as follows: - -#. Absolute: - - - ``https://odoo.com/documentation/{BRANCH}/applications/sales/sales/products_prices/prices.html`` - - ``https://odoo.com/documentation/{BRANCH}/applications/sales/sales/products_prices/products/variants.html`` - -#. 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. - -.. _contributing/line-length-limit: - -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. - -.. tip:: - You can safely break a line around the separators (``-->``) of ``menuselection`` markups and - anywhere in a hyperlink reference. For the ``doc``, ``ref`` and ``download`` markups, this is - only true for the label part of the reference. - -Example: Line breaks within markups ------------------------------------ - -.. code-block:: rst - - To register your seller account in Odoo, go to :menuselection:`Sales --> Configuration --> Settings - --> Amazon Connector --> Amazon Accounts` and click on :guilabel:`CREATE`. You can find the **Seller - ID** under the link :guilabel:`Your Merchant Token`. - -Be consistent with indentation +============================== +RST guidelines and cheat sheet ============================== -Use only spaces (never tabs). +.. important:: + We strongly recommend reading the :doc:`content_guidelines` and main :doc:`../documentation` + pages before contributing. -Use as many spaces at the beginning of an indented line as needed to align it with the first -character of the markup in the line above. This usually implies 3 spaces but you only need 2 for -bulleted lists. +Follow the RST guidelines below when contributing to the documentation to help maintain consistency +with the rest of the documentation and facilitate the review process for the team: -Example: The first ``:`` is below the ``i`` (3 spaces) ------------------------------------------------------- +- :ref:`Use formatting. ` +- :ref:`Be consistent with indentation. ` +- :ref:`Start a new line before the 100th character. ` -.. code-block:: rst +For hyperlinks: - .. image:: media/example.png - :align: center - :alt: example +- :ref:`Use relative links for internal URLs. ` +- :ref:`Do not break hyperlink targets when refactoring. ` +- :ref:`Do not use non-descriptive hyperlink labels. ` -Example: The ``:titlesonly:`` and page references start below the ``t`` (3 spaces) ----------------------------------------------------------------------------------- +.. _contributing/rst/formatting: -.. code-block:: rst +Formatting +========== - .. toctree:: - :titlesonly: +Use specific formatting to improve clarity and readability. For example, apply +:ref:`contributing/rst/menuselection` for menu paths, :ref:`contributing/rst/guilabel` +for other user interface elements, such as fields, buttons, and options, :ref:`contributing/rst/note` +for notes, :ref:`contributing/rst/example` for examples, etc. - payables/supplier_bills - payables/pay +.. note:: + Add a blank line between different block elements, such as paragraphs, lists, and directives to + ensure proper rendering and formatting. -Example: Continuation lines resume below the ``I``’s of “Invoice” (2 spaces) ----------------------------------------------------------------------------- +.. _contributing/rst/hyperlinks-guidelines: -.. code-block:: rst +Hyperlinks +========== - - 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. +.. _contributing/rst/relative-links: -.. _contributing/menuselection: +Internal URLs: relative links +----------------------------- -Use the menuselection markup -============================ +If you need to reference an :ref:`internal documentation page ` +or a :ref:`file ` that is not located in the same directory as the current +page, always use *relative file paths* instead of *absolute file paths*. This ensures that links +remain valid even with version updates, folder name changes, and directory structure +reorganizations. -Although chaining characters ``‣`` and menu names works fine to indicate a user which menus to -click, it is best to use the ``menuselection`` markup (see :ref:`contributing/menuselection`) 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 -markup is used inline as follows: ``:menuselection:`Sales --> Settings --> Products --> Variants```. +An absolute file path indicates the target's location from the root directory. A relative file path +uses smart notations (such as `../` that redirects to the parent folder) to indicate the target's +location *relative* to that of the source document. -.. _contributing/resilient-code: +.. example:: -Write resilient code -==================== + .. note:: + The purpose of the following example is to illustrate the difference between absolute and + relative links. Always use :ref:`contributing/rst/doc-hyperlinks` when referencing + documentation pages. -- 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. + Given the following source file tree: + :: -.. _contributing/hyperlink-target-prefix: + documentation + ├── content + │ └── applications + │ │ └── sales + │ │ │ └── sales + │ │ │ │ └── products_prices + │ │ │ │ │ └── products + │ │ │ │ │ │ └── import.rst + │ │ │ │ │ │ └── variants.rst + │ │ │ │ │ └── prices.rst -Prefix hyperlink targets with application names -=============================================== + A reference to :file:`prices.rst` and :file:`variants.rst` could be made from :file:`import.rst` + as follows: -As hyperlink targets are visible from the entire documentation when referenced with the ``ref`` -markup, it is recommended to prefix the target name with that of the related application. For -instance, naming a target ``_amazon/form`` instead of ``_form`` avoids unwanted behaviors and makes -the purpose of the target clear. + #. Absolute: -.. _contributing/hyperlink-target-resilience: + - `documentation/content/applications/sales/sales/products_prices/prices.rst` + - `documentation/content/applications/sales/sales/products_prices/products/variants.rst` -Don’t break hyperlink targets -============================= + #. Relative: + + - `../prices.rst` + - `variants.rst` + +.. _contributing/rst/update-targets: + +Refactoring: hyperlink targets +------------------------------ When refactoring (improving without adding new content) section headings or hyperlink targets, take care not to break any hyperlink reference to these targets or update them accordingly. -.. _contributing/single-underscore: +.. _contributing/rst/descriptive-labels: -Use single-underscore suffixes for hyperlink references -======================================================= +Hyperlink labels +---------------- -| Although using a double-underscore suffix works most of the time for classic hyperlink references, - it is not recommended as double-underscores normally indicate an anonymous hyperlink reference. - This is a special kind of hyperlink reference that makes use of nameless hyperlink targets - consisting only of two underscore. -| tl;dr: Double-underscore suffixes work until they don’t and are bad practice, use - single-underscore suffixes instead. +Do not use non-descriptive labels for :ref:`hyperlinks `. + +.. example:: + + | **Good example (descriptive label):** + | Please refer to the :doc:`Accounting documentation <../../../applications/finance/accounting>`. + + | **Bad example (non-descriptive label):** + | Please refer to :doc:`this page <../../../applications/finance/accounting>`. + +.. _contributing/rst/indentation: + +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 markup in the line above. This usually implies three spaces, but you only need two +for bulleted lists, for example. + +.. example:: + The first `:` is below the `i` (three spaces): + + .. code-block:: rst + + .. image:: media/example.png + :alt: example + + The `:titlesonly:` and page references start below the `t` (three spaces): + + .. code-block:: rst + + .. toctree:: + :titlesonly: + + payables/supplier_bills + payables/pay + + Continuation lines resume below the `I`’s of "Invoice" (two spaces): + + .. code-block:: rst + + - Invoice on ordered quantity: invoice the full order as soon as the sales order is confirmed. + - Invoice on delivered quantity: invoice on what was delivered even if it is a partial + delivery. + +.. _contributing/rst/character-limit: + +100th-character limit +===================== + +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**. It is not necessary to leave a +trailing whitespace at the end of a line to separate words. + +.. tip:: + - You can safely break a line on any space, even inside markups such as `menuselection` and + `doc`. + - Some external hyperlinks may exceed 100 characters, but leaving them on a single line is + acceptable. + +.. example:: + + .. code-block:: rst + + To register your seller account in Odoo, go to :menuselection:`Sales --> Configuration --> + Settings --> Amazon Connector --> Amazon Accounts` and click :guilabel:`Create`. You can find + the **Seller ID** under the link :guilabel:`Your Merchant Token`. + +.. _contributing/rst/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**. + +.. _contributing/rst/markups: + +Markups +======= + +.. _contributing/rst/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/rst/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/rst/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/rst/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/rst/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/rst/guilabel: + +:abbr:`GUI (graphical user interface)` element +---------------------------------------------- + +Use the `guilabel` markup to identify any text of the interactive user interface (e.g., labels). + +.. 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`. + +.. note:: + Avoid using the `guilabel` markup when referring to a concept or general term. + + .. example:: + - | **Good example:** + | To create a credit note, go to :menuselection:`Accounting --> Customers --> Invoices`, + open the invoice, and click :guilabel:`Credit Note`. + - | **Bad example:** + | To create a :guilabel:`Credit Note`, go to :menuselection:`Accounting --> Customers --> + Invoices`, open the :guilabel:`Invoice`, and click :guilabel:`Credit Note`. + +.. _contributing/rst/menuselection: + +Menu selection +-------------- + +Use the `menuselection` markup to guide users through a sequence of menus, starting with the app's +name. + +.. list-table:: + :class: o-showcase-table + + * - To review sales performance, go to :menuselection:`Sales --> Reporting --> Dashboard`. + + * - .. code-block:: text + + To review sales performance, go to :menuselection:`Sales --> Reporting --> Dashboard`. + +.. note:: + Only include actual menu items in the `menuselection` markup: + + - Use the :ref:`contributing/rst/guilabel` markup for other user interface elements, such as + buttons and section titles: + + .. code-block:: text + + To configure the bill control policy, navigate to :menuselection:`Purchase --> Configuration + --> Settings`, and scroll down to the :guilabel:`Invoicing` section. Under :guilabel:`Bill + Control`, select either :guilabel:`Ordered quantities` or :guilabel:`Received quantities`. + + - Do not include menu section names. For example, in the screenshot below, `Journals` should not + be included in the menu path :menuselection:`Accounting --> Accounting --> Journal Entries`: + + .. image:: rst_guidelines/accounting-menu.png + :alt: Accounting menu showing the Journals menu section. + +.. _contributing/rst/file: + +File +---- + +Use the `file` markup to indicate a file path or name. + + +.. list-table:: + :class: o-showcase-table + + * - Create redirections using the :file:`redirects.txt` file found at the root of the repository. + + * - .. code-block:: text + + Create redirections using the :file:`redirects.txt` file found at the root of the + repository. + +.. _contributing/rst/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/rst/icons: + +Icons +----- + +Use the `icon` markup to add the class name of an icon. There are two icon sets used in Odoo: +`FontAwesome4 `_ and :doc:`Odoo UI +`. Follow the icon with its name as a +:ref:`contributing/rst/guilabel` in brackets as a descriptor. + +.. 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/rst/lists: + +Lists +===== + +.. _contributing/rst/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/rst/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 `#.` instead of `1.`, `2.`, etc. for better code + resilience. + +.. _contributing/rst/nested-list: + +Nested lists +------------ + +.. tip:: + - Add a blank line before the nested elements in lists. + - :ref:`Indent ` nested lists properly, with sub-items aligned + under their parent item. + +.. 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/rst/hyperlinks: + +Hyperlinks +========== + +.. _contributing/rst/external-hyperlinks: + +External hyperlinks +------------------- + +External hyperlinks are links to a URL with a custom label. They follow the syntax: +```label `_``. + +.. note:: + - Use :ref:`documentation page hyperlinks ` when targeting + another documentation page. + - Do not use :ref:`non-descriptive hyperlink labels `. + +.. 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/rst/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 `_`` 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/rst/custom-anchors: + +Custom anchors +-------------- + +Custom anchors follow the same syntax as external hyperlink aliases but without any URL. They allow +referencing a specific part of a RST file by using the target as an anchor. When users click the +reference, they are taken to the part of the documentation page where the target is defined. + +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. + +.. important:: + As targets are visible from the entire documentation when referenced with the `ref` markup, + prefix the target name with the **app/section name** and the **file name**, separated by slashes, + e.g., `accounting/taxes/configuration`. + +.. note:: + - Add custom anchors for all headings so they can be referenced from any documentation file or + within Odoo using documentation links. + - Notice that there is no `_` at the end, contrary to what is done with :ref:`external hyperlinks + `. + +.. list-table:: + :class: o-showcase-table + + * - Please refer to the :ref:`contributing/rst/hyperlinks-guidelines` section to learn more + about :ref:`relative links `. + + * - .. code-block:: text + + .. _contributing/rst/hyperlinks-guidelines: + + Hyperlinks + ========== + + .. _contributing/rst/relative-links: + + Use relative links for internal URLs + ------------------------------------ + + Please refer to the :ref:`` section to learn more + about :ref:`relative links `. + +.. _contributing/rst/doc-hyperlinks: + +Documentation page hyperlinks +----------------------------- + +The `doc` markup allows referencing a documentation page wherever it is in the file tree through a +relative file path. There are two ways to use the markup, both using the `doc` 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 the :doc:`Accounting documentation + <../../../applications/finance/accounting>` to learn more about + :doc:`../../../applications/finance/accounting/customer_invoices`. + + * - .. code-block:: text + + Please refer to the :doc:`Accounting documentation <../../../applications/finance/accounting>` + to learn more about :doc:`../../../applications/finance/accounting/customer_invoices`. + +.. important:: + :ref:`Use relative links ` for documentation page hyperlinks. + +.. _contributing/rst/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 :download:`module structure template ` to start + building your module. + + * - .. code-block:: text + + Download this :download:`module structure template ` to start building your module. + +.. note:: + Store the file alongside other :ref:`media files ` and + reference it using a :ref:`relative link `. + +.. _contributing/rst/images: + +Images +====== + +The `image` markup allows inserting images in a document. + +.. list-table:: + :class: o-showcase-table + + * - .. image:: rst_guidelines/create-invoice.png + :alt: Create an invoice. + + * - .. code-block:: text + + .. image:: rst_guidelines/create-invoice.png + :alt: Create an invoice. + +.. tip:: + - Images should generally be aligned to the left, which is the default behavior. Use the `align` + parameter to change the alignment, e.g., `:align: center`. + - Use the `alt` parameter to add :ref:`contributing/content/alt-tags`, e.g., `:alt: Activating + the developer mode in the Settings app`. + - Use the `scale` parameter to scale the image, e.g., `:scale: 75%`. + +.. seealso:: + :ref:`Content guidelines for images ` + +.. _contributing/rst/alert-blocks: + +Alert blocks (admonitions) +========================== + +.. _contributing/rst/seealso: + +See also +-------- + +.. list-table:: + :class: o-showcase-table + + * - .. seealso:: + - :doc:`Accounting documentation <../../../applications/finance/accounting>` + - :doc:`../../../applications/sales/sales/invoicing/proforma` + - `Google documentation on setting up Analytics for a website + `_ + + * - .. code-block:: text + + .. seealso:: + - :doc:`Accounting documentation <../../../applications/finance/accounting>` + - :doc:`../../../applications/sales/sales/invoicing/proforma` + - `Google documentation on setting up Analytics for a website `_ + +.. _contributing/rst/note: + +Note +---- + +.. list-table:: + :class: o-showcase-table + + * - .. note:: + Use this alert block to draw the reader's attention and highlight important additional + information. + + * - .. code-block:: text + + .. note:: + Use this alert block to draw the reader's attention and highlight important additional information. + +.. _contributing/rst/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/rst/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/rst/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/rst/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/rst/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/rst/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/rst/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/rst/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 tables. Then, copy-paste the generated formatting into your document. + +.. _contributing/rst/code-blocks: + +Code blocks +=========== + +Use the `code-block` directive to show example code. Specify the language (e.g., python, xml, etc.) +to format the code according to the language's syntax rules. + +.. 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/rst/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/rst/tabs: + +Content tabs +============ + +.. warning:: + 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/rst/basic-tabs: + +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/rst/nested-tabs: + +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/rst/group-tabs: + +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/rst/code: + +Code tabs +--------- + +Use the `code-tab` markup to create code tabs, which are essentially :ref:`group tabs +` that treat the tabs' content as a :ref:`code block +`. Specify the language to format the code according to the language's +syntax rules. If a label is set, it is used for grouping tabs instead of the language name. + +.. 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/rst/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, tips, and tricks to help you create clear and effective content. + + .. 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, tips, and tricks to help you create clear and effective content. + + .. card:: RST guidelines + :target: rst_guidelines + + List of technical guidelines to observe when writing with reStructuredText. + +.. _contributing/rst/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. | ++-----------------+--------------------------------------------------------------------------------+ +| `hide-page-toc` | Hide the "On this page" sidebar and use full page width for the content. | ++-----------------+--------------------------------------------------------------------------------+ +| `nosearch` | Exclude the document from search results. | ++-----------------+--------------------------------------------------------------------------------+ +| `orphan` | Suppress the need to include the document in a toctree. | ++-----------------+--------------------------------------------------------------------------------+ +| `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`. | ++-----------------+--------------------------------------------------------------------------------+ +| `custom-css` | Link CSS files (comma-separated) to the file. | ++-----------------+--------------------------------------------------------------------------------+ +| `custom-js` | Link JS files (comma-separated) to the document. | ++-----------------+--------------------------------------------------------------------------------+ +| `classes` | Assign the specified classes to the `
` element of the file. | ++-----------------+--------------------------------------------------------------------------------+ + +.. _contributing/rst/formatting-tips: + +Formatting tips +=============== + +.. _contributing/rst/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/rst/escaping: + +Escape markup symbols +--------------------- + +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```. + +.. seealso:: + `Docutils documentation on reStructuredText directives and roles + `_ diff --git a/content/contributing/documentation/rst_guidelines/accounting-menu.png b/content/contributing/documentation/rst_guidelines/accounting-menu.png new file mode 100644 index 000000000..baf223ff6 Binary files /dev/null and b/content/contributing/documentation/rst_guidelines/accounting-menu.png differ diff --git a/content/contributing/documentation/rst_guidelines/create-invoice.png b/content/contributing/documentation/rst_guidelines/create-invoice.png new file mode 100644 index 000000000..956ac4ebb Binary files /dev/null and b/content/contributing/documentation/rst_guidelines/create-invoice.png differ diff --git a/content/contributing/documentation/rst_guidelines/my_module.zip b/content/contributing/documentation/rst_guidelines/my_module.zip new file mode 100644 index 000000000..97a63dfb7 Binary files /dev/null and b/content/contributing/documentation/rst_guidelines/my_module.zip differ diff --git a/content/contributing/handle_reviews.rst b/content/contributing/handle_reviews.rst deleted file mode 100644 index 7a13f017b..000000000 --- a/content/contributing/handle_reviews.rst +++ /dev/null @@ -1,4 +0,0 @@ -As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team will be -automatically assigned for review. If the reviewer has questions or remarks, they will post them as -comments and you will be notified by email. Those comments must be resolved for the contribution to -go forward. diff --git a/redirects/15.0.txt b/redirects/15.0.txt index eeee0fdde..840f68f32 100644 --- a/redirects/15.0.txt +++ b/redirects/15.0.txt @@ -185,6 +185,10 @@ applications/websites/website/reporting/google_analytics_dashboard.rst applicati applications/websites/website/configuration/on-premise_geo-ip-installation.rst administration/on_premise/geo_ip.rst applications/websites/website/configuration/unsplash.rst applications/general/integrations/unsplash.rst # websites/website/configuration/ -> general/integrations/* +# contributing/documentation + +contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst + # developer/howtos developer/howtos/rdtraining/D_mixins.rst developer/tutorials/mixins.rst # reorganize the developer doc diff --git a/redirects/16.0.txt b/redirects/16.0.txt index 2fc4170d5..dfd735953 100644 --- a/redirects/16.0.txt +++ b/redirects/16.0.txt @@ -185,6 +185,10 @@ applications/websites/website/optimize/plausible.rst applications/websites/websi applications/websites/website/reporting/google_analytics.rst applications/websites/website/reporting/analytics.rst # merged plausible.rst and google_analytics.rst applications/websites/website/reporting/plausible.rst applications/websites/website/reporting/analytics.rst # merged plausible.rst and google_analytics.rst +# contributing/documentation + +contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst + # developer/howtos developer/howtos/discover_js_framework.rst developer/tutorials/discover_js_framework.rst # reorganize the developer doc diff --git a/redirects/17.0.txt b/redirects/17.0.txt index ef18db38a..8097973e6 100644 --- a/redirects/17.0.txt +++ b/redirects/17.0.txt @@ -118,3 +118,7 @@ applications/websites/ecommerce/managing_products/cross_upselling.rst applicatio applications/finance/accounting/get_started/vat_units.rst applications/finance/accounting/get_started/tax_units.rst # vat_units --> tax_units applications/finance/accounting/taxes/taxcloud.rst applications/finance/accounting/taxes.rst # taxcloud --> taxes + +# contributing/documentation + +contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst diff --git a/redirects/saas-17.2.txt b/redirects/saas-17.2.txt new file mode 100644 index 000000000..525180398 --- /dev/null +++ b/redirects/saas-17.2.txt @@ -0,0 +1,3 @@ +# contributing/documentation + +contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst diff --git a/redirects/saas-17.4.txt b/redirects/saas-17.4.txt new file mode 100644 index 000000000..525180398 --- /dev/null +++ b/redirects/saas-17.4.txt @@ -0,0 +1,3 @@ +# contributing/documentation + +contributing/documentation/rst_cheat_sheet.rst contributing/documentation/rst_guidelines.rst