[MERGE] Forward-port of branch 13.0 to 14.0

Makefile

@@ -1,6 +1,6 @@
 # Makefile for Sphinx documentation
 
-# Pass WORKERS=auto for parallel build
+# Pass WORKERS=1 for single-worker build
 ifndef WORKERS
   WORKERS = auto
 endif

README.md

@@ -4,10 +4,10 @@
 
 ### Requirements
 
-- [Git](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html#install-git)
+- [Git](https://www.odoo.com/documentation/14.0/contributing/documentation.html#install-git)
-- [Python 3.6, 3.7, or 3.8](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html#python)
+- [Python 3.6, 3.7, or 3.8](https://www.odoo.com/documentation/14.0/contributing/documentation.html#python)
 - Python dependencies listed in the file [`requirements.txt`](https://github.com/odoo/documentation/tree/14.0/requirements.txt).
-- [Make](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html#make)
+- [Make](https://www.odoo.com/documentation/14.0/contributing/documentation.html#make)
 - A local copy of the [odoo/odoo repository in 14.0](https://github.com/odoo/odoo/tree/14.0) (Optional)
 
 ### Instructions
@@ -23,7 +23,7 @@
 
 2. Open the file `documentation/_build/html/index.html` in your web browser to display the render.
 
-3. See [this guide](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html#preview-your-changes)
+3. See [this guide](https://www.odoo.com/documentation/14.0/contributing/documentation.html#preview-your-changes)
    for more detailed instructions.
 
 Optional: to fully build the developer documentation with inline docstrings for documented Python
@@ -34,7 +34,7 @@ be shown.
 ## Contribute to the documentation
 
 For contributions to the content of the documentation, please refer to the
-[Introduction Guide](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html).
+[Introduction Guide](https://www.odoo.com/documentation/14.0/contributing/documentation.html).
 
 To **report a content issue**, **request new content** or **ask a question**, use the
 [repository's issue tracker](https://github.com/odoo/documentation-user/issues) as usual.

content/contributing.rst

@@ -1,4 +1,3 @@
-
 ============
 Contributing
 ============

content/contributing/documentation.rst

@@ -1,12 +1,404 @@
+:show-content:
 
-=================================
+===================
-Contributing to the documentation
+Write documentation
-=================================
+===================
 
 .. toctree::
    :titlesonly:
 
-   documentation/introduction_guide
+   documentation/content_guidelines
    documentation/rst_cheat_sheet
    documentation/rst_guidelines
-   documentation/content_guidelines
+
+**First of all, thank you for landing here and helping us improve the user documentation of Odoo!**
+
+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.
+
+.. _contributing/rst-intro:
+
+reStructuredText
+================
+
+Our documentation is written in **reStructuredText** (RST), a `lightweight markup language
+<https://en.wikipedia.org/wiki/Lightweight_markup_language>`_ consisting of normal 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 only small changes to the content.
+
+If you need to learn about a specific markup, head over to :doc:`our cheat sheet for RST
+<documentation/rst_cheat_sheet>` which contains all the information that you should ever need for
+the user documentation of Odoo.
+
+.. important::
+   We kindly ask you to observe a set of :doc:`content <documentation/content_guidelines>` and
+   :doc:`RST <documentation/rst_guidelines>` 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 they are reviewed by a redactor at Odoo.
+
+.. seealso::
+   - :doc:`documentation/content_guidelines`
+   - :doc:`documentation/rst_cheat_sheet`
+   - :doc:`documentation/rst_guidelines`
+
+.. _contributing/getting-started:
+
+Getting started
+===============
+
+As our documentation is maintained on GitHub, you will need a free GitHub account. Click `here
+<https://github.com/join>`_ to create one.
+
+Now, depending on whether you want to update existing content, or rather work on new content and
+make file changes, you have two courses of action:
+
+#. **For small changes** in ``.rst`` files only, i.e. addition/edition of paragraphs or typos, **we
+   suggest that you use the GitHub interface**. This is the easiest and fasted way to submit your
+   request for changes for the documentation and is suitable for non-technical people. Read
+   :ref:`contributing/github-interface` to learn how to use this method.
+#. **For more complex cases**, it is necessary to **use Git and work from a local copy of the
+   documentation**. This method seems intimidating but only requires basic knowledge of Git. See
+   :ref:`contributing/canonical-git-workflow` for more information on this method.
+
+.. _contributing/github-interface:
+
+Use the GitHub interface
+========================
+
+#. 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.
+
+   .. image:: documentation/version-selector.png
+
+#. Head over to the page that you want to change and click on the **Edit on GitHub** button in the
+   bottom of the left menu.
+
+   .. image:: documentation/edit-on-github.png
+
+#. If you do not have edit rights on the repository (`odoo/documentation
+   <https://github.com/odoo/documentation>`_), you need to fork it by clicking on the appropriate
+   button. In other terms, you create a copy of the entire repository on your own account. If you do
+   have the edit rights, skip this step.
+
+   .. image:: documentation/fork-repository.png
+
+#. Make the appropriate changes while taking care of following the :doc:`content
+   <documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>` guidelines.
+
+#. Click on the **Preview changes** button to review your contribution in a more human-readable
+   format. Be aware that the preview is not able to handle all markups correctly. Notes and tips,
+   for instance, are not correctly rendered. The version of your content published to the website
+   will be, however.
+
+#. Go to the bottom of the page to create a commit (:dfn:`what packs your changes together and
+   labels them with a commit message`) of your changes.
+
+   #. | In first text box, describe your changes. For instance, "Fix a typo" and "Add documentation
+        for invoicing of sales orders" are two clear commit messages.
+      | In the second text box, justify *why* you made these changes, if you feel that it is not
+        obvious.
+   #. Select the option "Create a new branch for this commit and start a pull request." if you have
+      the choice (if you have partial or full edit writes on the repository). If not, skip this
+      step.
+   #. Click on the green button. It is either labelled "Commit changes" or "Propose file change".
+
+   .. image:: documentation/commit-changes.png
+
+#. In the dropdown for the selection of the base branch (i.e., the version of the documentation that
+   your changes concern), make sure to select the same version as in the first step of this guide
+   and click on the **Create pull request** button.
+
+   .. image:: documentation/select-branches-base.png
+
+#. Double-check your :abbr:`PR (Pull Request)` and, when ready, click again on the **Create pull
+   request** button to submit your changes for review by a content writer at Odoo.
+
+   .. image:: documentation/create-pull-request.png
+
+#. You're done! If your changes are approved straight away they will appear in the documentation the
+   very next day. It may also be the case that the reviewer has a question or a remark, so make sure
+   to check your notifications or your emails, depending on your account settings.
+
+.. _contributing/canonical-git-workflow:
+
+Use the canonical Git workflow
+==============================
+
+.. _contributing/prepare-machine:
+
+Prepare your machine
+--------------------
+
+.. _contributing/install-git:
+
+Install Git
+~~~~~~~~~~~
+
+We use `Git <https://en.wikipedia.org/wiki/Git>`_ to manage the files of the user documentation.
+It is a tool that allows to track the history of changes made to a file and, more importantly, to
+work on different versions of those files at the same time. It means that you do not need to worry
+about overwriting someone else’s pending work when you start editing the documentation.
+
+You must then configure Git to identify yourself as the author of your future contribution. Enter
+the same email address as the one you used to register on GitHub.
+
+#. Download and install **Git** on your machine.
+#. Verify that `the installation folder of Git is included in your system's PATH variable
+   <win-add-to-path_>`_.
+#. Execute the following commands in a terminal:
+
+   .. code-block:: console
+
+      $ git config --global user.name “Your Name”
+      $ git config --global user.email “youremail@example.com”
+
+.. _contributing/fetch-sources:
+
+Fetch the sources
+~~~~~~~~~~~~~~~~~
+
+As stated earlier, our documentation (in all its versions) is maintained on GitHub at
+`github.com/odoo/documentation <https://github.com/odoo/documentation>`_. A modification is made by
+the mean of a :abbr:`PR (Pull Request)` (:dfn:`proposal of content changes`) to allow for a review
+of the changes before updating the sources of the documentation.
+
+Prior to submitting a modification, you need to make a copy of the sources and download that copy on
+your machine.
+
+#. Go to `github.com/odoo/documentation <https://github.com/odoo/documentation>`_ and click on the
+   **Fork** button in the top right corner.
+
+   .. image:: documentation/fork-button.png
+
+#. Execute the following commands in a terminal:
+
+   .. code-block:: console
+
+      $ git clone https://github.com/odoo/documentation
+      $ cd documentation/
+
+   .. important::
+      If you do not have edit rights on the repository owned by Odoo, replace "odoo" with your
+      Github username in the URL of the command above. If you do have edit rights, it is not
+      necessary to fork the repository.
+
+#. In order to ease the collaboration between writers coming from many different systems and teams,
+   execute the following group of commands that correspond to your :abbr:`OS (Operating System)` in
+   a terminal.
+
+   - Windows:
+
+     .. code-block:: doscon
+
+        $ cd documentation/
+        $ git config --global core.autocrlf true
+        $ git config commit.template %CD%\commit_template.txt
+
+   - Linux or Mac OS:
+
+     .. code-block:: console
+
+        $ cd documentation/
+        $ git config --global core.autocrlf input
+        $ git config commit.template `pwd`/commit_template.txt
+
+.. _contributing/python:
+
+Python
+~~~~~~
+
+Because the documentation is written in :abbr:`RST (reStructuredText)`, it needs to be built
+(:dfn:`converted to HTML`) in order to display nicely. This is done by the documentation generator
+which takes the original :abbr:`RST (reStructuredText)` files as input, transforms the markups
+in a human-readable format, and outputs HTML files to be read in your web browser.
+
+The documentation generator that we use is called `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
+and is written in `Python <https://en.wikipedia.org/wiki/Python_(programming_language)>`_. You have
+to install Python in order to use Sphinx. For the record, Sphinx is the program and Python the
+programming language, but you do not need to know much more about them so don't panic!
+
+Python comes with its own package manager: `pip
+<https://en.wikipedia.org/wiki/Pip_(package_manager)>`_. It allows installing Python dependencies in
+a single command.
+
+#. Download and install the recommended release (`see README file
+   <https://github.com/odoo/documentation/tree/14.0/README.md>`_) of **Python 3** on your machine.
+#. Make sure to have **pip** installed on your machine (on Windows, you can install pip alongside
+   Python).
+#. Execute the following commands in a terminal to verify that both installations finished
+   successfully:
+
+   .. code-block:: console
+
+      $ python3 --version
+      $ pip3 --version
+
+#. Execute the following commands in a terminal to install the Python dependencies of the
+   documentation:
+
+   .. code-block:: console
+
+      $ cd documentation/
+      $ pip3 install -r requirements.txt
+
+.. note::
+   Depending on your :abbr:`OS (Operating System)`, you may need to run the commands ``python`` and
+   ``pip`` instead of ``python3`` and ``pip3``
+
+.. _contributing/make:
+
+Make
+~~~~
+
+`Make <https://en.wikipedia.org/wiki/Make_(software)>`_ is a tool that packs a bunch of
+command-lines into one to be easier to remember and to type. In our case, it is used to execute
+complex Sphinx build commands by using a single and simpler one instead.
+
+#. Download and install **Make** on your machine.
+#. Verify that `the installation folder of Make is included in your system's PATH variable
+   <win-add-to-path_>`_.
+
+.. _contributing/pngquant:
+
+pngquant
+~~~~~~~~
+
+`pngquant <https://pngquant.org/>`_ is a tool that we use to compress PNG images so that the
+documentation does not end up weighting several Gigabytes in a few year span.
+
+#. Download and install **pngquant** on your machine.
+#. Verify that `the installation folder of pngquant is included in your system's PATH variable
+   <win-add-to-path_>`_.
+
+.. _contributing/prepare-version:
+
+Prepare your version
+--------------------
+
+Now that your machine is all set up, it is time to do the same for your version of the documentation
+files. As it would not be convenient to have several people working on the version 13.0 in parallel
+(conflicts of content would occur all the time), and in order to be able to create a :abbr:`PR
+(Pull Request)`, you must `create a new branch
+<https://www.atlassian.com/git/tutorials/using-branches>`_ starting from the branch 13.0. In other
+words, you copy the entirety of this version’s files and give it another name. For this example, we
+will go with ``13.0-my_contribution``.
+
+Execute the following commands in a terminal to...
+
+#. Navigate to the documentation folder:
+
+   .. code-block:: console
+
+      $ cd documentation/
+
+#. Switch to the version 13.0:
+
+   .. code-block:: console
+
+      $ git checkout 13.0
+
+#. Create your own branch which will be a copy of 13.0:
+
+   .. code-block:: console
+
+      $ git checkout -b 13.0-my_contribution
+
+.. _contributing/perform-changes:
+
+Perform your changes
+--------------------
+
+You can now perform any change you want to the documentation files. These changes must be compliant
+with :abbr:`RST (reStructuredText)` syntax (see :doc:`documentation/rst_cheat_sheet`) and with our
+:doc:`content <documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>`
+guidelines.
+
+.. important::
+   If your changes include the addition of a new image, for instance :file:`my_image.png`, proceed
+   as follows:
+
+   #. Make sure that the image is in ``.png`` format.
+   #. Execute the following commands in a terminal:
+
+      .. code-block:: console
+
+         $ cd path-to-the-directory-of-the-image/
+         $ pngquant my_image.png
+
+   #. Delete :file:`my_image.png`.
+   #. Rename :file:`my_image-fs8.png` to :file:`my_image.png`.
+
+.. _contributing/preview-changes:
+
+Preview your changes
+--------------------
+
+To preview your changes in a generated documentation, proceed as follows:
+
+#. Execute the following commands in a terminal:
+
+   .. code-block:: console
+
+      $ cd documentation/
+      $ make clean
+      $ make html
+
+   .. tip::
+      You can omit the :command:`make clean` command when no recent change has been made to the
+      hierarchy of documentation files.
+
+#. Fix any error or warning shown in the logs of the build.
+#. Open the file :file:`documentation/_build/html/index.html` with your default web browser.
+
+.. note::
+   These steps have for only purpose to show you the final results of your changes. They have no
+   impact on the documentation source files.
+
+.. _contributing/submit-changes:
+
+Submit your changes
+-------------------
+
+.. important::
+   We expect you to have basic knowledge of Git, which should be enough to cover the basic flow of a
+   one-time contribution. If you plan on submitting several contributions, work on older versions of
+   the documentation or perform any other advanced action, we recommend you to be confident with
+   Git. Help yourself with `this manual of Git <https://www.atlassian.com/git>`_ and `this
+   interactive tutorial <https://learngitbranching.js.org/>`_.
+
+#. Execute the following commands in a terminal:
+
+   .. code-block:: console
+
+      $ git add *
+      $ git commit
+      $ git push -u origin 13.0-my_contribution
+
+#. Go to `github.com/odoo/documentation/pulls
+   <https://github.com/odoo/documentation/pulls>`_ and click on the **New pull request** button.
+
+   .. image:: documentation/new-pull-request.png
+
+#. If you forked the base repository in the section :ref:`contributing/fetch-sources`, click on the
+   link **compare across forks** If not, skip this step.
+
+   .. image:: documentation/compare-across-forks.png
+
+#. In the dropdown for the selection of the base branch (i.e., the version of the documentation that
+   your changes concern), make sure to select the version that your changes target (here **13.0**).
+
+   .. image:: documentation/select-branches-fork.png
+
+#. Double-check your :abbr:`PR (Pull Request)` and, when ready, click again on the **Create pull
+   request** button to submit your changes for review by a redactor at Odoo.
+
+   .. image:: documentation/create-pull-request.png
+
+#. You're done! If your changes are approved straight away they will appear in the documentation the
+   very next day. It may also be the case that the reviewer has a question or a remark, so make sure
+   to check your notifications or your emails, depending on your account settings.
+
+
+.. _win-add-to-path: https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/

content/contributing/documentation/content_guidelines.rst

@@ -1,4 +1,3 @@
-
 ==================
 Content guidelines
 ==================
@@ -12,7 +11,7 @@ writing style, some rules still apply to give the reader more clarity and compre
    section of the documentation. Good knowledge of the ins and outs of **RST writing** is required
    to write and submit your contribution. Note that it also affects your writing style itself.
 
-   - :doc:`introduction_guide`
+   - :doc:`../documentation`
    - :doc:`rst_cheat_sheet`
    - :doc:`rst_guidelines`
 
@@ -82,33 +81,33 @@ To write good titles and headings:
   - proper nouns (brands, product and service names, etc.)
   - app features, as written in the apps
 
-  .. important::
+.. important::
-     Do not capitalize common nouns when they are not referred to as features. This is more likely
+   Do not capitalize common nouns when they are not referred to as features. This is more likely
-     to happen in headings rather than in titles.
+   to happen in headings rather than in titles.
 
-  +------------------+-----------------------------------+--------------------------------------------------------+
++------------------+-----------------------------------+--------------------------------------------------------+
-  |                  | Examples                          | Explanations                                           |
+|                  | Examples                          | Explanations                                           |
-  +==================+===================================+========================================================+
++==================+===================================+========================================================+
-  | | **Titles**     | *Quotation Templates*             | "Quotation Templates" is a feature in Odoo.            |
+| | **Titles**     | *Quotation Templates*             | "Quotation Templates" is a feature in Odoo.            |
-  | | (h1)           +-----------------------------------+--------------------------------------------------------+
+| | (h1)           +-----------------------------------+--------------------------------------------------------+
-  |                  | *Lead Mining*                     | "Lead Mining" is a feature in Odoo.                    |
+|                  | *Lead Mining*                     | "Lead Mining" is a feature in Odoo.                    |
-  |                  +-----------------------------------+--------------------------------------------------------+
+|                  +-----------------------------------+--------------------------------------------------------+
-  |                  | *Resupply from another Warehouse* | "Warehouse" is capitalized as we refer to the feature  |
+|                  | *Resupply from another Warehouse* | "Warehouse" is capitalized as we refer to the feature  |
-  |                  |                                   | in the app rather than to a real warehouse.            |
+|                  |                                   | in the app rather than to a real warehouse.            |
-  |                  +-----------------------------------+--------------------------------------------------------+
+|                  +-----------------------------------+--------------------------------------------------------+
-  |                  | *Synchronize Google Calendar      | "Google Calendar" is a product and "Odoo" is a brand.  |
+|                  | *Synchronize Google Calendar      | "Google Calendar" is a product and "Odoo" is a brand.  |
-  |                  | with Odoo*                        |                                                        |
+|                  | with Odoo*                        |                                                        |
-  +------------------+-----------------------------------+--------------------------------------------------------+
++------------------+-----------------------------------+--------------------------------------------------------+
-  | | **Headings**   | *Confirm the quotation*           | "The quotation" is a common noun not referring to a    |
+| | **Headings**   | *Confirm the quotation*           | "The quotation" is a common noun not referring to a    |
-  | | (h2, h3, etc.) |                                   | feature in Odoo.                                       |
+| | (h2, h3, etc.) |                                   | feature in Odoo.                                       |
-  |                  +-----------------------------------+--------------------------------------------------------+
+|                  +-----------------------------------+--------------------------------------------------------+
-  |                  | *Test environment*                | "Environment" is a common noun.                        |
+|                  | *Test environment*                | "Environment" is a common noun.                        |
-  |                  +-----------------------------------+--------------------------------------------------------+
+|                  +-----------------------------------+--------------------------------------------------------+
-  |                  | *Add a new Payment Acquirer*      | "Payment Acquirers" is a feature in Odoo.              |
+|                  | *Add a new Payment Acquirer*      | "Payment Acquirers" is a feature in Odoo.              |
-  |                  +-----------------------------------+--------------------------------------------------------+
+|                  +-----------------------------------+--------------------------------------------------------+
-  |                  | *Generate SEPA Direct Debit XML   | "SEPA Direct Debit" and "XML" are considered as proper |
+|                  | *Generate SEPA Direct Debit XML   | "SEPA Direct Debit" and "XML" are considered as proper |
-  |                  | files to submit payments*         | nouns.                                                 |
+|                  | files to submit payments*         | nouns.                                                 |
-  +------------------+-----------------------------------+--------------------------------------------------------+
++------------------+-----------------------------------+--------------------------------------------------------+
 
 .. _contributing/document-structure:
 
@@ -185,7 +184,7 @@ A few tips to improve your screenshots:
 #. If necessary, you can **edit** the screenshot to remove unnecessary fields and to narrow even
    more Odoo's display.
 
-.. image:: media/screenshot-tips.gif
+.. image:: content_guidelines/screenshot-tips.gif
    :align: center
    :alt: Three tips to take good screenshots for the Odoo documentation.
 

content/contributing/documentation/introduction_guide.rst

@@ -1,395 +0,0 @@
-
-==================
-Introduction guide
-==================
-
-**First of all, thank you for landing here and helping us improve the user documentation of Odoo!**
-
-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.
-
-.. _contributing/rst-intro:
-
-reStructuredText
-================
-
-Our documentation is written in **reStructuredText** (RST), a `lightweight markup language
-<https://en.wikipedia.org/wiki/Lightweight_markup_language>`_ consisting of normal 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 only small changes to the content.
-
-If you need to learn about a specific markup, head over to :doc:`our cheat sheet for RST
-<rst_cheat_sheet>` which contains all the information that you should ever need for the user
-documentation of Odoo.
-
-.. important::
-   We kindly ask you to observe a set of :doc:`content <content_guidelines>` and :doc:`RST
-   <rst_guidelines>` 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 they
-   are reviewed by a redactor at Odoo.
-
-.. seealso::
-   - :doc:`rst_cheat_sheet`
-   - :doc:`rst_guidelines`
-   - :doc:`content_guidelines`
-
-.. _contributing/getting-started:
-
-Getting started
-===============
-
-As our documentation is maintained on GitHub, you will need a free GitHub account. Click `here
-<https://github.com/join>`_ to create one.
-
-Now, depending on whether you want to update existing content, or rather work on new content and
-make file changes, you have two courses of action:
-
-#. **For small changes** in ``.rst`` files only, i.e. addition/edition of paragraphs or typos, **we
-   suggest that you use the GitHub interface**. This is the easiest and fasted way to submit your
-   request for changes for the documentation and is suitable for non-technical people. Read
-   :ref:`contributing/github-interface` to learn how to use this method.
-#. **For more complex cases**, it is necessary to **use Git and work from a local copy of the
-   documentation**. This method seems intimidating but only requires basic knowledge of Git. See
-   :ref:`contributing/canonical-git-workflow` for more information on this method.
-
-.. _contributing/github-interface:
-
-Use the GitHub interface
-========================
-
-#. 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.
-
-   .. image:: media/version-selector.png
-
-#. Head over to the page that you want to change and click on the **Edit on GitHub** button in the
-   bottom of the left menu.
-
-   .. image:: media/edit-on-github.png
-
-#. If you do not have edit rights on the repository (`odoo/documentation
-   <https://github.com/odoo/documentation>`_), you need to fork it by clicking on the appropriate
-   button. In other terms, you create a copy of the entire repository on your own account. If you do
-   have the edit rights, skip this step.
-
-   .. image:: media/fork-repository.png
-
-#. Make the appropriate changes while taking care of following the :doc:`guidelines
-   <rst_guidelines>`.
-
-#. Click on the **Preview changes** button to review your contribution in a more human-readable
-   format. Be aware that the preview is not able to handle all markups correctly. Notes and tips,
-   for instance, are not correctly rendered. The version of your content published to the website
-   will be, however.
-
-#. Go to the bottom of the page to create a commit (:dfn:`what packs your changes together and
-   labels them with a commit message`) of your changes.
-
-   #. | In first text box, describe your changes. For instance, "Fix a typo" and "Add documentation
-        for invoicing of sales orders" are two clear commit messages.
-      | In the second text box, justify *why* you made these changes, if you feel that it is not
-        obvious.
-   #. Select the option "Create a new branch for this commit and start a pull request." if you have
-      the choice (if you have partial or full edit writes on the repository). If not, skip this
-      step.
-   #. Click on the green button. It is either labelled "Commit changes" or "Propose file change".
-
-   .. image:: media/commit-changes.png
-
-#. In the dropdown for the selection of the base branch (i.e., the version of the documentation that
-   your changes concern), make sure to select the same version as in the first step of this guide
-   and click on the **Create pull request** button.
-
-   .. image:: media/select-branches-base.png
-
-#. Double-check your :abbr:`PR (Pull Request)` and, when ready, click again on the **Create pull
-   request** button to submit your changes for review by a content writer at Odoo.
-
-   .. image:: media/create-pull-request.png
-
-#. You're done! If your changes are approved straight away they will appear in the documentation the
-   very next day. It may also be the case that the reviewer has a question or a remark, so make sure
-   to check your notifications or your emails, depending on your account settings.
-
-.. _contributing/canonical-git-workflow:
-
-Use the canonical Git workflow
-==============================
-
-.. _contributing/prepare-machine:
-
-Prepare your machine
---------------------
-
-.. _contributing/install-git:
-
-Install Git
-~~~~~~~~~~~
-
-We use `Git <https://en.wikipedia.org/wiki/Git>`_ to manage the files of the user documentation.
-It is a tool that allows to track the history of changes made to a file and, more importantly, to
-work on different versions of those files at the same time. It means that you do not need to worry
-about overwriting someone else’s pending work when you start editing the documentation.
-
-You must then configure Git to identify yourself as the author of your future contribution. Enter
-the same email address as the one you used to register on GitHub.
-
-#. Download and install **Git** on your machine.
-#. Verify that `the installation folder of Git is included in your system's PATH variable
-   <win-add-to-path_>`_.
-#. Execute the following commands in a terminal:
-
-   .. code-block:: console
-
-      $ git config --global user.name “Your Name”
-      $ git config --global user.email “youremail@example.com”
-
-.. _contributing/fetch-sources:
-
-Fetch the sources
-~~~~~~~~~~~~~~~~~
-
-As stated earlier, our documentation (in all its versions) is maintained on GitHub at
-`github.com/odoo/documentation <https://github.com/odoo/documentation>`_. A modification is made by
-the mean of a :abbr:`PR (Pull Request)` (:dfn:`proposal of content changes`) to allow for a review
-of the changes before updating the sources of the documentation.
-
-Prior to submitting a modification, you need to make a copy of the sources and download that copy on
-your machine.
-
-#. Go to `github.com/odoo/documentation <https://github.com/odoo/documentation>`_ and click on the
-   **Fork** button in the top right corner.
-
-   .. image:: media/fork-button.png
-
-#. Execute the following commands in a terminal:
-
-   .. code-block:: console
-
-      $ git clone https://github.com/odoo/documentation
-      $ cd documentation/
-
-   .. important::
-      If you do not have edit rights on the repository owned by Odoo, replace "odoo" with your
-      Github username in the URL of the command above. If you do have edit rights, it is not
-      necessary to fork the repository.
-
-#. In order to ease the collaboration between writers coming from many different systems and teams,
-   execute the following group of commands that correspond to your :abbr:`OS (Operating System)` in
-   a terminal.
-
-   - Windows:
-
-     .. code-block:: doscon
-
-        $ cd documentation/
-        $ git config --global core.autocrlf true
-        $ git config commit.template %CD%\commit_template.txt
-
-   - Linux or Mac OS:
-
-     .. code-block:: console
-
-        $ cd documentation/
-        $ git config --global core.autocrlf input
-        $ git config commit.template `pwd`/commit_template.txt
-
-.. _contributing/python:
-
-Python
-~~~~~~
-
-Because the documentation is written in :abbr:`RST (reStructuredText)`, it needs to be built
-(:dfn:`converted to HTML`) in order to display nicely. This is done by the documentation generator
-which takes the original :abbr:`RST (reStructuredText)` files as input, transforms the markups
-in a human-readable format, and outputs HTML files to be read in your web browser.
-
-The documentation generator that we use is called `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
-and is written in `Python <https://en.wikipedia.org/wiki/Python_(programming_language)>`_. You have
-to install Python in order to use Sphinx. For the record, Sphinx is the program and Python the
-programming language, but you do not need to know much more about them so don't panic!
-
-Python comes with its own package manager: `pip
-<https://en.wikipedia.org/wiki/Pip_(package_manager)>`_. It allows installing Python dependencies in
-a single command.
-
-#. Download and install the recommended release (`see README file
-   <https://github.com/odoo/documentation/tree/14.0/README.md>`_) of **Python 3** on your machine.
-#. Make sure to have **pip** installed on your machine (on Windows, you can install pip alongside
-   Python).
-#. Execute the following commands in a terminal to verify that both installations finished
-   successfully:
-
-   .. code-block:: console
-
-      $ python3 --version
-      $ pip3 --version
-
-#. Execute the following commands in a terminal to install the Python dependencies of the
-   documentation:
-
-   .. code-block:: console
-
-      $ cd documentation/
-      $ pip3 install -r requirements.txt
-
-.. note::
-   Depending on your :abbr:`OS (Operating System)`, you may need to run the commands ``python`` and
-   ``pip`` instead of ``python3`` and ``pip3``
-
-.. _contributing/make:
-
-Make
-~~~~
-
-`Make <https://en.wikipedia.org/wiki/Make_(software)>`_ is a tool that packs a bunch of
-command-lines into one to be easier to remember and to type. In our case, it is used to execute
-complex Sphinx build commands by using a single and simpler one instead.
-
-#. Download and install **Make** on your machine.
-#. Verify that `the installation folder of Make is included in your system's PATH variable
-   <win-add-to-path_>`_.
-
-.. _contributing/pngquant:
-
-pngquant
-~~~~~~~~
-
-`pngquant <https://pngquant.org/>`_ is a tool that we use to compress PNG images so that the
-documentation does not end up weighting several Gigabytes in a few year span.
-
-#. Download and install **pngquant** on your machine.
-#. Verify that `the installation folder of pngquant is included in your system's PATH variable
-   <win-add-to-path_>`_.
-
-.. _contributing/prepare-version:
-
-Prepare your version
---------------------
-
-Now that your machine is all set up, it is time to do the same for your version of the documentation
-files. As it would not be convenient to have several people working on the version 14.0 in parallel
-(conflicts of content would occur all the time), and in order to be able to create a :abbr:`PR
-(Pull Request)`, you must `create a new branch
-<https://www.atlassian.com/git/tutorials/using-branches>`_ starting from the branch 14.0. In other
-words, you copy the entirety of this version’s files and give it another name. For this example, we
-will go with ``14.0-my_contribution``.
-
-Execute the following commands in a terminal to...
-
-#. Navigate to the documentation folder:
-
-   .. code-block:: console
-
-      $ cd documentation/
-
-#. Switch to the version 14.0:
-
-   .. code-block:: console
-
-      $ git checkout 14.0
-
-#. Create your own branch which will be a copy of 14.0:
-
-   .. code-block:: console
-
-      $ git checkout -b 14.0-my_contribution
-
-.. _contributing/perform-changes:
-
-Perform your changes
---------------------
-
-You can now perform any change you want to the documentation files. These changes must be compliant
-with :abbr:`RST (reStructuredText)` syntax (see :doc:`rst_cheat_sheet`) and with our
-:doc:`guidelines <rst_guidelines>`.
-
-.. important::
-   If your changes include the addition of a new image, for instance :file:`my_image.png`, proceed
-   as follows:
-
-   #. Make sure that the image is in ``.png`` format.
-   #. Execute the following commands in a terminal:
-
-      .. code-block:: console
-
-         $ cd path-to-the-directory-of-the-image/
-         $ pngquant my_image.png
-
-   #. Delete :file:`my_image.png`.
-   #. Rename :file:`my_image-fs8.png` to :file:`my_image.png`.
-
-.. _contributing/preview-changes:
-
-Preview your changes
---------------------
-
-To preview your changes in a generated documentation, proceed as follows:
-
-#. Execute the following commands in a terminal:
-
-   .. code-block:: console
-
-      $ cd documentation/
-      $ make clean
-      $ make html
-
-   .. tip::
-      You can omit the :command:`make clean` command when no recent change has been made to the
-      hierarchy of documentation files.
-
-#. Fix any error or warning shown in the logs of the build.
-#. Open the file :file:`documentation/_build/html/index.html` with your default web browser.
-
-.. note::
-   These steps have for only purpose to show you the final results of your changes. They have no
-   impact on the documentation source files.
-
-.. _contributing/submit-changes:
-
-Submit your changes
--------------------
-
-.. important::
-   We expect you to have basic knowledge of Git, which should be enough to cover the basic flow of a
-   one-time contribution. If you plan on submitting several contributions, work on older versions of
-   the documentation or perform any other advanced action, we recommend you to be confident with
-   Git. Help yourself with `this manual of Git <https://www.atlassian.com/git>`_ and `this
-   interactive tutorial <https://learngitbranching.js.org/>`_.
-
-#. Execute the following commands in a terminal:
-
-   .. code-block:: console
-
-      $ git add *
-      $ git commit
-      $ git push -u origin 14.0-my_contribution
-
-#. Go to `github.com/odoo/documentation/pulls
-   <https://github.com/odoo/documentation/pulls>`_ and click on the **New pull request** button.
-
-   .. image:: media/new-pull-request.png
-
-#. If you forked the base repository in the section :ref:`contributing/fetch-sources`, click on the
-   link **compare across forks** If not, skip this step.
-
-   .. image:: media/compare-across-forks.png
-
-#. In the dropdown for the selection of the base branch (i.e., the version of the documentation that
-   your changes concern), make sure to select the version that your changes target (here **14.0**).
-
-   .. image:: media/select-branches-fork.png
-
-#. Double-check your :abbr:`PR (Pull Request)` and, when ready, click again on the **Create pull
-   request** button to submit your changes for review by a redactor at Odoo.
-
-   .. image:: media/create-pull-request.png
-
-#. You're done! If your changes are approved straight away they will appear in the documentation the
-   very next day. It may also be the case that the reviewer has a question or a remark, so make sure
-   to check your notifications or your emails, depending on your account settings.
-
-
-.. _win-add-to-path: https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/

content/contributing/documentation/rst_cheat_sheet.rst

@@ -1,4 +1,3 @@
-
 ===============
 RST cheat sheet
 ===============
@@ -328,7 +327,7 @@ RST
 Render
 ******
 
-.. image:: media/create-invoice.png
+.. image:: rst_cheat_sheet/create-invoice.png
    :align: center
    :alt: Create an invoice
    :height: 100

content/contributing/documentation/rst_guidelines.rst

@@ -1,4 +1,3 @@
-
 ==============
 RST guidelines
 ==============

extensions/odoo_theme/layout.html

@@ -64,7 +64,7 @@
     </nav>
     <header class="o_main_header border-bottom navbar navbar-light navbar-expand-lg">
         {%- include "layout_templates/header.html" %}
-        <button class="navbar-toggler pe-3 border-0" type="button" data-bs-toggle="collapse" data-bs-target="#o_main_toctree" aria-label="Toggle navigation">
+        <button class="navbar-toggler p-0 border-0" type="button" data-bs-toggle="collapse" data-bs-target="#o_main_toctree" aria-label="Toggle navigation">
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>

extensions/odoo_theme/layout_templates/homepage.html

@@ -123,8 +123,13 @@
                 <h5 class="text-muted pt-3 text-uppercase fw_semibold">Top Links</h5>
                 <ul class="list-unstyled">
                     <li>
-                        <a href="{{ pathto('contributing/documentation/introduction_guide') }}" class="stretched-link">
+                        <a href="{{ pathto('contributing/documentation') }}" class="stretched-link">
-                            Introduction guide
+                            Write documentation
+                        </a>
+                    </li>
+                    <li>
+                        <a href="{{ pathto('contributing/documentation/content_guidelines') }}" class="stretched-link">
+                            Content guidelines
                         </a>
                     </li>
                 </ul>

extensions/odoo_theme/static/js/menu.js

@@ -21,22 +21,32 @@
      * TOC entries (<li> elements) that are on the path of the displayed page receive the
      * `o_active_toc_entry` class, and their related (parent) TOC entry list (<ul> elements) receive
      * the `show` (Bootstrap) class.
-     * Also, the deepest TOC entry receives the `o_deepest_active_toc_entry` class, and its child
+     * Also, the deepest TOC entries of their respective branch receive the
-     * TOC entry list receives the `show` class.
+     * `o_deepest_active_toc_entry` class, and their child TOC entry lists receive the `show` class.
      */
     const _flagActiveTocEntriesAndLists = () => {
-        let deepestTocEntry = undefined;
+        const regexLayer = /\btoctree-l(?<layer>\d+)\b/;
+        let lastLayer = undefined;
+        let lastTocEntry = undefined;
+        const deepestTocEntries = [];
         this.navigationMenu.querySelectorAll('.current').forEach(element => {
             if (element.tagName === 'UL') {
-                // Expand all related <ul>
+                element.classList.add('show'); // Expand all related <ul>
-                element.classList.add('show');
             } else if (element.tagName === 'LI') {
-                // Highlight all <li> in the active hierarchy
+                element.classList.add('o_active_toc_entry'); // Highlight all active <li>
-                element.classList.add('o_active_toc_entry');
+                let match = regexLayer.exec(element.className);
-                deepestTocEntry = element;
+                let currentLayer = parseInt(match.groups.layer, 10);
+                if (lastLayer && currentLayer <= lastLayer) { // We just moved to another branch
+                    deepestTocEntries.push(lastTocEntry);
+                }
+                lastLayer = currentLayer;
+                lastTocEntry = element;
             }
         })
-        if (deepestTocEntry) {
+        if (lastTocEntry) {
+            deepestTocEntries.push(lastTocEntry); // The last TOC entry is the deepest of its branch
+        }
+        deepestTocEntries.forEach(deepestTocEntry => {
             const childTocEntryList = deepestTocEntry.querySelector('ul');
             if (childTocEntryList) {
                 childTocEntryList.classList.add('show');
@@ -44,7 +54,7 @@
                 deepestTocEntry = deepestTocEntry.parentElement.parentElement;
             }
             deepestTocEntry.classList.add('o_deepest_active_toc_entry');
-        }
+        });
     };
 
      document.addEventListener('scroll', () => {

extensions/odoo_theme/static/scss/_variables.scss

@@ -234,7 +234,7 @@ $o-header-white:                            #ffffff;
 
 // Navigation
 $o-side-nav-width:                          350px;
-$o-on-page-width:                           25%;
+$o-on-page-width:                           20%;
 
 // o_has_code_column pages
 $o-halfpage-width:                          54%;
@@ -247,4 +247,12 @@ $website-2x-prefix:                         "2x_";
 // Animations and Transitions
 $o-ease:                                    cubic-bezier(.55,0,.1,1);
 
+// Paddings and margins
 
+$padding-xs:                                .5rem;
+$padding-s:                                 1rem;
+$padding-m:                                 2rem;
+$padding-l:                                 3rem;
+$margin-s:                                  $padding-s;
+$margin-m:                                  $padding-m;
+$margin-l:                                  $padding-l;

extensions/odoo_theme/static/style.scss

@@ -49,14 +49,17 @@ header.o_main_header {
     right: 0;
     background-color: $o-header-white;
     z-index: 10;
+    padding: 0 $padding-s;
     @include media-breakpoint-up(lg) {
         height: $o-header-height;
-        padding-right: 3rem;
+        padding: 0 $padding-m;
+    }
+    @include media-breakpoint-up(xl) {
+        padding: 0 $padding-l;
     }
 
-    .o_logo_wrapper {
-        padding: 0 1rem;
 
+    .o_logo_wrapper {
         > .o_logo {
             img {
                 margin-bottom: -2px;
@@ -70,25 +73,45 @@ header.o_main_header {
             }
         }
         @include media-breakpoint-up(xl) {
-            width: $o-side-nav-width;
+            width: calc(#{$o-side-nav-width} - #{$padding-l});
         }
         @include media-breakpoint-up(lg) {
-            padding-left: 3rem;
+            margin-right: $margin-l;
-            margin-right: 3rem;
         }
     }
+
+    .o_logo img {
+        @include media-breakpoint-up(lg) {
+            height: 30px
+        }
+    }
+
     .o_search_wrapper {
         display: flex;
         opacity: 1;
         @include transition(opacity .3s);
-
         @include media-breakpoint-down(lg) {
             display: block;
             position: absolute;
-            width: 100%;
+            width: calc(100% - (#{$padding-s} * 2));
-            padding: 0 10px;
+            top: calc(100% + #{$padding-s});
-            top: calc(100% + 15px);
        }
+
+        .o_search {
+            position: relative;
+            width: 100%;
+            @include media-breakpoint-up(lg) {
+                max-width: 500px;
+            }
+
+            .btn {
+                @include o-position-absolute($top: 50%, $right: 1rem);
+                @include o-transform (translateY(-50%)) ;
+                padding: 0;
+                font-size: 1.2rem;
+                color: $gray;
+            }
+        }
     }
 
     &.o_header_scrolled {
@@ -99,7 +122,6 @@ header.o_main_header {
         }
     }
 
-
     .highlight-link {
         @media only screen and (max-width: 1242px) and (min-width: 992px){
             position: absolute;
@@ -114,9 +136,8 @@ header.o_main_header {
             @include font-size($font-size-secondary);
         }
     }
-    .navbar-toggler {
-        border: none;
 
+    .navbar-toggler {
         &[aria-expanded="true"] {
             .icon-bar {
                 &:nth-of-type(1) {
@@ -135,6 +156,7 @@ header.o_main_header {
                 }
             }
         }
+
         .icon-bar {
             display: block;
             width: 22px;
@@ -167,63 +189,44 @@ header.o_main_header {
     }
 }
 
-.o_logo img {
-    @include media-breakpoint-up(lg) {
-        height: 30px
-    }
-}
-
-.o_search_wrapper {
-    .o_search {
-        position: relative;
-        width: 100%;
-        @include media-breakpoint-up(lg) {
-            max-width: 500px;
-        }
-
-        .btn {
-            @include o-position-absolute($top: 50%, $right: 1rem);
-            @include o-transform (translateY(-50%)) ;
-            padding: 0;
-            font-size: 1.2rem;
-            color: $gray;
-        }
-    }
-}
-
 //------------------------------------------------------------------------------
 // Left side nav toctree
 //------------------------------------------------------------------------------
 
 .o_side_nav {
     width: 100%;
-    height: calc(100vh - #{$o-header-mobile-height});
+    height: 100%;
     overflow-y: auto;
     position: fixed;
     top: -100%;
     left:0;
-
-    &.show {
-        top: $o-header-mobile-height;
-    }
-    @include media-breakpoint-up(lg) {
-        width: $o-side-nav-width;
-        height: calc(100vh - #{$o-header-height});
-        top: $o-header-height;
-        padding-top: 2rem;
-        padding-left: 3rem;
-    }
     @include o-transition(all, .3s);
     padding-top: 4rem;
-    padding-left: 1rem;
+    padding-left: $padding-s;
     background-color: lighten($o-violet-dark, 70%) ;
     z-index: 10;
     @include font-size($font-size-secondary);
     color: $o-violet-dark;
+    @include media-breakpoint-up(lg) {
+        width: calc(#{$o-side-nav-width} - 1rem);
+        height: calc(100vh - #{$o-header-height});
+        top: $o-header-height;
+        padding-top: $padding-m;
+        padding-left: $padding-m;
+    }
+    @include media-breakpoint-up(xl) {
+        width: $o-side-nav-width;
+        padding-top: $padding-l;
+        padding-left: $padding-l;
+    }
+
+    &.show {
+        top: $o-header-mobile-height;
+    }
 
     .toctree-l1 {
-        padding-top: .5rem;
+        padding-top: $padding-xs;
-        padding-bottom: .5rem;
+        padding-bottom: $padding-xs;
     }
 
     ul {
@@ -281,14 +284,11 @@ header.o_main_header {
 .o_side_nav, .o_page_toc_nav {
     ul { // all uls in toc
         list-style: none;
-        padding-left: 1rem;
+        padding-left: $padding-s;
 
         li {
-            &.toctree_l2 {
-                padding-left: .2rem;
-            }
             > a.reference {
-                padding-left: .8rem;
+                padding-left: .875rem;
             }
 
             a {
@@ -315,7 +315,7 @@ header.o_main_header {
 
                     > i[class^="i-"] {
                         display: inline-block;
-                        margin-right: .2rem;
+                        margin-right: .125rem;
                         @include o-transition(rotate, .3s);
                         font-size: .75rem;
                         font-weight: $fw_bold;
@@ -353,7 +353,7 @@ header.o_main_header {
     aside.o_page_toc {
         display: none;
         @include font-size($font-size-secondary);
-        @include media-breakpoint-up(lg) {
+        @include media-breakpoint-up(xl) {
             display: block;
             position: -webkit-sticky;
             position: sticky;
@@ -362,7 +362,7 @@ header.o_main_header {
             width: $o-on-page-width;
             height: 100%;
             max-height: calc(100vh - #{$o-header-height});
-            padding: 3rem 3rem 3rem 0;
+            padding: $padding-l $padding-s $padding-l 0;
             overflow-y: auto;
         }
 
@@ -370,8 +370,8 @@ header.o_main_header {
             text-transform: uppercase;
             font-weight: $fw_bold;
             color: $gray-darker;
-            padding-left: .5rem;
+            padding-left: $padding-xs;
-            margin-bottom: .5rem;
+            margin-bottom: $padding-xs;
         }
 
         a {
@@ -417,21 +417,22 @@ header.o_main_header {
 
     main {
         position: relative;
-        padding-top: 3rem;
+        padding-top: 5rem;
-        @include media-breakpoint-down(lg) {
+        padding-bottom: $padding-l;
-            padding-top: 7rem;
-        }
-        padding-bottom: 3rem;
         @include media-breakpoint-up(lg) {
-            left: $o-side-nav-width;
+            left: calc(#{$o-side-nav-width} - #{$padding-s});
-            max-width: calc(100vw - (#{$o-side-nav-width} + var(--bs-gutter-x, 1.5rem)) - #{$o-on-page-width});
+            max-width: calc(100vw - #{$o-side-nav-width});
-            padding: 3rem;
+            padding: $padding-l;
             margin: 0;
         }
+        @include media-breakpoint-up(xl) {
+            left: $o-side-nav-width;
+            max-width: calc(100vw - #{$o-side-nav-width} - #{$o-on-page-width});
+        }
 
         &.o_index, &.o_fullwidth_page, &.o_has_code_column {
-            @include media-breakpoint-up(lg) {
+            @include media-breakpoint-up(xl) {
-                max-width: calc(100vw - (#{$o-side-nav-width} + var(--bs-gutter-x, 1rem)) );
+                max-width: calc(100vw - #{$o-side-nav-width});
             }
         }
 
@@ -439,13 +440,17 @@ header.o_main_header {
 
         &.o_index {
             .o_content_fw_banner {
-                margin: -3rem -0.75rem 3rem;
+                margin: 0 -0.75rem $margin-m;
-                padding: 2rem 1rem;
+                padding: $padding-m $padding-s;
                 align-items: center;
                 @include o-gradient();
                 @include media-breakpoint-up(lg) {
-                    margin: -3rem -3rem 3rem;
+                    margin: -#{$margin-m} -#{$margin-m} $margin-m;
-                    padding: 2rem 3rem;
+                    padding: $padding-m $padding-m;
+                }
+                @include media-breakpoint-up(xl) {
+                    margin: -#{$margin-l} -#{$margin-l} $margin-l;
+                    padding: $padding-l $padding-l;
                 }
 
                 .btn-primary {
@@ -466,7 +471,7 @@ header.o_main_header {
             ul {
                 > li {
                     position: relative;
-                    padding-bottom: .5rem;
+                    padding-bottom: $padding-xs;
                     display: flex;
                     align-items: center;
 
@@ -490,9 +495,9 @@ header.o_main_header {
                 display: block;
                 color: $gray-darker;
                 @include font-size($h2-font-size);
-                padding-bottom: .5rem;
+                padding-bottom: $padding-xs;
                 border-bottom: 1px solid $gray-light;
-                margin-bottom: 1rem;
+                margin-bottom: $margin-s;
             }
         }
 
@@ -531,7 +536,7 @@ header.o_main_header {
                     }
 
                     .o_git_link {
-                        right: calc(#{$o-codecol-width} + 2rem);
+                        right: calc(#{$o-codecol-width} + $padding-l);
                     }
 
                     section {
@@ -555,7 +560,7 @@ header.o_main_header {
                             float: none;
                             clear: none;
                             margin-left: 57%;
-                            padding: 1rem;
+                            padding: $padding-s;
 
                             blockquote {
                                 font-weight: $fw_semibold;
@@ -606,9 +611,9 @@ header.o_main_header {
 
             .o_git_link {
                 @include font-size($font-size-secondary);
-                @include o-position-absolute($top: 0px, $right: 1rem);
+                @include o-position-absolute($top: 0px, $right: $margin-s);
                 @include media-breakpoint-up(lg) {
-                    @include o-position-absolute($top: 10px, $right: 1rem);
+                    @include o-position-absolute($top: 10px, $right: $margin-s);
                 }
                 i {
                     margin-right: .2rem;
@@ -629,7 +634,7 @@ header.o_main_header {
                     padding-left: 0;
 
                     li {
-                        padding-bottom: .5rem;
+                        padding-bottom: $padding-xs;
                     }
                 }
             }
@@ -647,26 +652,26 @@ header.o_main_header {
                         max-width: calc(100% - 120px);
                     }
                     + * {
-                        margin-top: 1rem;
+                        margin-top: $margin-s;
                     }
                 }
 
                 > h2 {
                     font-family: $font-family-serif;
                     color: $gray-darker;
-                    margin-top: 2rem;
+                    margin-top: $margin-m;
-                    margin-bottom: 1rem;
+                    margin-bottom: $margin-s;
                     padding-bottom: .3rem;
                     border-bottom: 1px solid $gray-light;
                 }
 
                 > h3 {
-                    margin-top: 2rem;
+                    margin-top: $margin-m;
                     font-weight: $fw_bold;
                 }
 
                 > h4 {
-                    margin-top: 2rem;
+                    margin-top: $margin-l;
                 }
 
                 > h4, > h5, > h6 {
@@ -964,11 +969,11 @@ header.o_main_header {
 //------------------------------------------------------------------------------
 footer {
     .o_get_help {
-        padding-top: 3rem;
+        padding-top: $padding-l;
-        padding-bottom: 3rem;
+        padding-bottom: $padding-l;
         background: $gray-lighter;
         @include media-breakpoint-up(lg) {
-            padding-left: calc(#{$o-side-nav-width} + 3rem)
+            padding-left: calc(#{$o-side-nav-width} + #{$padding-l})
         }
 
         h5 {

redirects.txt

@@ -31,8 +31,11 @@ contributing/documentation/guidelines.rst contributing/documentation/rst_guideli
 # Redirections introduced in 12.0 :
 
 administration/odoo_sh/documentation.rst administration/odoo_sh.rst # moved during doc-apocalypse (#945)
+
 support/user_doc.rst contributing/documentation/introduction_guide.rst  # removed in forward-port of #544 (b109c3af)
 
+contributing/documentation/introduction_guide.rst contributing/documentation.rst  # flatten hierarchy: introduction_guide --> ../
+
 # Redirections introduced in 13.0 :
 
 sales/sale_amazon.rst applications/sales/sales/amazon_connector.rst                # sale_amazon -> amazon_connector (#524)