[MERGE] Forward-port of branch 11.0 to 12.0

_extensions/odoo/__init__.py

@@ -28,9 +28,9 @@ def setup(app):
     app.connect('html-page-context', update_meta)
 
 def update_meta(app, pagename, templatename, context, doctree):
-    meta = context.get('meta')
-    if meta is None:
-        meta = context['meta'] = {}
+    if not context.get('meta'):  # context['meta'] can be None
+        context['meta'] = {}
+    meta = context.setdefault('meta', {})  # we want {} by default
     meta.setdefault('banner', app.config.odoo_cover_default)
 
 def navbarify(node, navbar=None):

_extensions/odoo/pycompat.py

@@ -1,27 +0,0 @@
-# -*- coding: utf-8 -*-
-import sys
-
-PY2 = sys.version_info[0] == 2
-
-if PY2:
-    text_type = unicode
-else:
-    text_type = str
-
-def to_text(source):
-    """ Generates a text value (an instance of text_type) from an arbitrary 
-    source.
-
-    * False and None are converted to empty strings
-    * text is passed through
-    * bytes are decoded as UTF-8
-    * rest is textified via the current version's relevant data model method
-    """
-    if source is None or source is False:
-        return u''
-
-    if isinstance(source, bytes):
-        return source.decode('utf-8')
-
-    return text_type(source)
-

_extensions/odoo/translator.py

@@ -2,14 +2,11 @@
 import os.path
 import posixpath
 import re
-import urllib
 
 from docutils import nodes
 from sphinx import addnodes, util
 from sphinx.locale import admonitionlabels
 
-from . import pycompat
-
 try:
     from urllib import url2pathname
 except ImportError:
@@ -58,6 +55,7 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
         self.context = []
         self.section_level = 0
 
+        self.config = builder.config
         self.highlightlang = self.highlightlang_base = self.builder.config.highlight_language
         self.highlightopts = getattr(builder.config, 'highlight_options', {})
 
@@ -67,7 +65,7 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
         self.param_separator = ','
 
     def encode(self, text):
-        return pycompat.to_text(text).translate({
+        return text.translate({
             ord('&'): u'&',
             ord('<'): u'&lt;',
             ord('"'): u'&quot;',
@@ -76,7 +74,7 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
         })
 
     def starttag(self, node, tagname, **attributes):
-        tagname = pycompat.to_text(tagname).lower()
+        tagname = tagname.lower()
 
         # extract generic attributes
         attrs = {name.lower(): value for name, value in attributes.items()}
@@ -111,7 +109,7 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
     # only "space characters" SPACE, CHARACTER TABULATION, LINE FEED,
     # FORM FEED and CARRIAGE RETURN should be collapsed, not al White_Space
     def attval(self, value, whitespace=re.compile(u'[ \t\n\f\r]')):
-        return self.encode(whitespace.sub(u' ', pycompat.to_text(value)))
+        return self.encode(whitespace.sub(u' ', str(value)))
 
     def astext(self):
         return u''.join(self.body)
@@ -432,7 +430,12 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
             tagname = 'th'
         else:
             tagname = 'td'
-        self.body.append(self.starttag(node, tagname))
+        attrs = {}
+        if 'morerows' in node:
+            attrs['rowspan'] = node['morerows']+1
+        if 'morecols' in node:
+            attrs['colspan'] = node['morecols']+1
+        self.body.append(self.starttag(node, tagname, **attrs))
         self.context.append(tagname)
     def depart_entry(self, node):
         self.body.append(u'</{}>'.format(self.context.pop()))
@@ -647,7 +650,7 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
             self.body.append(title if title else util.nodes.clean_astext(env.titles[ref]))
             self.body.append(u'</h2>')
 
-            entries = [(title, ref)] if not toc else ((e[0], e[1]) for e in toc[0]['entries'])
+            entries = [(title, ref)] if not toc else ((e[0], e[1]) for e in list(toc)[0]['entries'])
             for subtitle, subref in entries:
                 baseuri = self.builder.get_target_uri(node['parent'])
 

contributing.rst

@@ -0,0 +1,10 @@
+:banner: banners/contributing.png
+
+============
+Contributing
+============
+
+.. toctree::
+   :titlesonly:
+
+   contributing/documentation

contributing/documentation.rst

@@ -0,0 +1,12 @@
+:banner: banners/contributing.png
+
+=================================
+Contributing to the documentation
+=================================
+
+.. toctree::
+   :titlesonly:
+
+   documentation/introduction_guide
+   documentation/rst_cheat_sheet
+   documentation/guidelines

contributing/documentation/guidelines.rst

@@ -0,0 +1,162 @@
+:banner: banners/contributing.png
+
+==========
+Guidelines
+==========
+
+.. _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 ``../`` git 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-user
+  ├── 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/user/13.0/sales/products_prices/prices.html``
+   - ``https://odoo.com/documentation/user/13.0/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`` directives and
+   anywhere in a hyperlink reference. For the ``doc``, ``ref`` and ``download`` directives, this is
+   only true for the label part of the reference.
+
+Example: Line breaks within directive and inline markup
+-------------------------------------------------------
+
+.. code-block:: rst
+
+   To register your seller account in Odoo, navigate to :menuselection:`Sales --> Configuration
+   --> Settings --> Amazon Connector --> Amazon Accounts` and click on **CREATE**. The **Seller
+   ID** can be found under the link **Your Merchant Token**.
+
+Be consistent with 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 directive in the line above. This usually implies 3 spaces but you only need 2 for
+bulleted lists.
+
+Example: The first ``:`` is below the ``i`` (3 spaces)
+------------------------------------------------------
+
+.. code-block:: rst
+
+   .. image:: media/example.png
+      :align: center
+      :alt: example
+
+Example: The ``:titlesonly:`` and page references start below the ``t`` (3 spaces)
+----------------------------------------------------------------------------------
+
+.. code-block:: rst
+
+   .. toctree::
+      :titlesonly:
+
+      payables/supplier_bills
+      payables/pay
+
+Example: Continuation lines resume below the ``I``’s of “Invoice” (2 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 you delivered even if it's a partial delivery.
+
+.. _contributing/menuselection:
+
+Use the menuselection directive
+===============================
+
+Although chaining characters ``‣`` and menu names works fine to indicate a user which menus to
+click, it is best to use the ``menuselection`` directive (see
+:ref:`contributing/specialized-directives`) 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 directive is used inline as follows:
+``:menuselection:`Settings --> Products --> Variants```.
+
+.. _contributing/resilient-code:
+
+Write resilient code
+====================
+
+- 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.
+
+.. _contributing/hyperlink-target-prefix:
+
+Prefix hyperlink targets with application names
+===============================================
+
+As hyperlink targets are visible from the entire documentation when referenced with the ``ref``
+directive, 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.
+
+.. _contributing/hyperlink-target-resilience:
+
+Don’t break 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:
+
+Use single-underscore suffixes for hyperlink references
+=======================================================
+
+| 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.

contributing/documentation/introduction_guide.rst

@@ -0,0 +1,399 @@
+:banner: banners/contributing.png
+
+==================
+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.
+
+.. note::
+   This tutorial only concern the `user documentation
+   <https://www.odoo.com/documentation/user/index.html>`_ of Odoo. The documentation for `developing
+   in Odoo <https://www.odoo.com/documentation/master/index.html>`_ in maintained alongside the
+   source code of Odoo at `github.com/odoo/odoo <https://github.com/odoo/odoo/tree/master/doc>`_.
+
+.. _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:`guidelines <guidelines>` as you write :abbr:`RST
+   (reStructuredText)`. 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:`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-user
+   <https://github.com/odoo/documentation-user>`_), 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 <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 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.
+
+.. _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-user <https://github.com/odoo/documentation-user>`_. 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-user <https://github.com/odoo/documentation-user>`_ 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-user
+      $ cd documentation-user/
+
+   .. 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-user/
+        $ git config --global core.autocrlf true
+        $ git config commit.template %CD%\commit_template.txt
+
+   - Linux or Mac OS:
+
+     .. code-block:: console
+
+        $ cd documentation-user/
+        $ 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 latest release 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-user/
+      $ 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-user/
+
+#. 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:`rst_cheat_sheet`) and with our
+:doc:`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-user/
+      $ 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-user/_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-user/pulls
+   <https://github.com/odoo/documentation-user/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 **13.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/

contributing/documentation/rst_cheat_sheet.rst

@@ -0,0 +1,549 @@
+:banner: banners/contributing.png
+
+===============
+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    | Min/Max number of occurrences |
++==============+===============+===============================+
+| H1           | | ``=======`` | 1/1                           |
+|              | | ``Heading`` |                               |
+|              | | ``=======`` |                               |
++--------------+---------------+-------------------------------+
+| H2           | | ``Heading`` | 0/∞                           |
+|              | | ``=======`` |                               |
++--------------+---------------+-------------------------------+
+| H3           | | ``Heading`` | 0/∞                           |
+|              | | ``-------`` |                               |
++--------------+---------------+-------------------------------+
+| H4           | | ``Heading`` | 0/∞                           |
+|              | | ``~~~~~~~`` |                               |
++--------------+---------------+-------------------------------+
+| H5           | | ``Heading`` | 0/∞                           |
+|              | | ``*******`` |                               |
++--------------+---------------+-------------------------------+
+| H6           | | ``Heading`` | 0/∞                           |
+|              | | ``^^^^^^^`` |                               |
++--------------+---------------+-------------------------------+
+
+.. _contributing/markup:
+
+Markup
+======
+
+.. _contributing/inline-markup:
+
+Inline markup
+-------------
+
+Use the following markups to emphasize your text to your liking:
+
++--------------+----------+
+| \*\*Text\*\* | **Text** |
++--------------+----------+
+| \*Text\*     | *Text*   |
++--------------+----------+
+| \`\`Text\`\` | ``Text`` |
++--------------+----------+
+
+.. seealso::
+   - :ref:`contributing/specialized-directives`
+
+.. _contributing/bulleted-list:
+
+Bulleted list
+-------------
+
+.. code-block:: rst
+
+   - This is a bulleted list.
+   - It has two items, the second
+     item uses two lines.
+
+.. code-block:: rst
+
+   * This is a bulleted list too.
+   * The principle stays the same.
+
+.. _contributing/numbered-list:
+
+Numbered list
+-------------
+
+.. code-block:: rst
+
+   #. This is a numbered list.
+   #. Numbering is automatic.
+
+.. code-block:: rst
+
+   1. This is a numbered list too.
+   2. Use this format to specify the numbering.
+
+.. _contributing/nested-list:
+
+Nested lists
+------------
+
+.. code-block:: rst
+
+   - This is the first item of a bulleted list.
+
+     1. It has a nested numbered list
+     2. with two items.
+
+.. _contributing/hyperlinks:
+
+Hyperlinks
+==========
+
+.. _contributing/hyperlink-references:
+
+Hyperlink references
+--------------------
+
+Hyperlink references are links to a URL with a custom label. They follow this syntax:
+```label <URL>`_``
+
+.. note::
+   The URL can be a relative path to a file within the documentation.
+
+Example
+~~~~~~~
+
+This excerpt of :abbr:`RST (reStructuredText)`: ``For instance, `this is a hyperlink reference
+<https://odoo.com>`_.`` is rendered as follows in HTML: “For instance, `this is a hyperlink
+reference <https://odoo.com>`_.”
+
+.. _contributing/external-hyperlink-targets:
+
+External hyperlink targets
+--------------------------
+
+| External hyperlink targets allow creating shortcuts for hyperlink references.
+| 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 <target_>`_`` does exactly what you expect: the label replaces the name of the target,
+   and the target is replaced by the URL.
+
+Example
+~~~~~~~
+
+RST
+***
+
+.. code-block:: rst
+
+   .. _proof-of-concept: https://en.wikipedia.org/wiki/Proof_of_concept
+
+   A proof-of-concept_ is a simplified version, a prototype of what is expected to agree on the main
+   lines of expected changes. `PoC <proof-of-concept_>`_ is a common abbreviation.
+
+Render
+******
+
+A `proof-of-concept <https://en.wikipedia.org/wiki/Proof_of_concept>`_ is a simplified version, a
+prototype of what is expected to agree on the main lines of expected changes. `PoC
+<https://en.wikipedia.org/wiki/Proof_of_concept>`_ is a common abbreviation.
+
+.. _contributing/internal-hyperlink-targets:
+
+Internal hyperlink targets
+--------------------------
+
+Internal hyperlink targets follow the same syntax as external hyperlink targets 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 target.
+
+.. important::
+   Targets can be referenced from other files than the ones in which they are defined.
+
+| The definition syntax is: ``.. _target:``
+| There are two ways to reference them, both using the ``ref`` directive:
+
+#. ``:ref:`target``` creates a hyperlink to the anchor with the heading defined below as label.
+#. ``:ref:`label <target>``` 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::
+  Notice that there is no ``_`` at the end, as it is done with :ref:`hyperlink targets
+  <contributing/hyperlink-references>`.
+
+Example
+~~~~~~~
+
+RST
+***
+
+.. code-block:: rst
+
+   .. _sales/quotation/start-of-page:
+
+   This can easily be done by creating a new product, see :ref:`product` for additional help.
+
+   .. _sales/quotation/product:
+
+   How to create a product?
+   =========================
+
+   As explained at the :ref:`start of the page <sales/quotation/start-of-page>`, ...
+
+Render
+******
+
+This can easily be done by creating a new product, see `How to create a product?
+<https://example.com/product>`_ for additional help.
+
+**How to create a product?**
+
+As explained at the `start of the page <https://example.com/scroll-to-start-of-page>`_, ...
+
+.. _contributing/implicit-hyperlink-targets:
+
+Implicit hyperlink targets
+--------------------------
+
+| Implicit hyperlink targets are a special kind of internal hyperlink targets: they are
+  automatically generated by section titles, footnotes, etc. Consequently, they don’t have a
+  definition syntax.
+| They can be referenced the same first way as external hyperlink targets by using the name of the
+  section title as URL.
+
+Example
+~~~~~~~
+
+RST
+***
+
+.. code-block:: rst
+
+   This can easily be done by creating a new user, see `How to create a new user?`_ for
+   additional help.  ...
+
+Render
+******
+
+This can easily be done by creating a new user, see `How to create a new user?
+<https://example.com/how-to-create-a-user>`_ for additional help. ...
+
+.. _contributing/doc:
+
+The ``doc`` directive
+---------------------
+
+| The ``doc`` directive allows referencing a documentation page wherever it is in the file tree
+  through a relative file path.
+| As usual, there are two ways to use the directive:
+
+#. ``:doc:`path_to_doc_page``` creates a hyperlink reference to the documentation page with the
+   title of the page as label.
+#. ``:doc:`label <path_to_doc_page>``` creates a hyperlink reference to the documentation page with
+   the given label.
+
+Example
+~~~~~~~
+
+RST
+***
+
+.. code-block:: rst
+
+   Please refer to :doc:`this documentation <customer_invoices>` and to
+   :doc:`../sales/invoicing/proforma`.
+
+Render
+******
+
+Please refer to `this documentation <https://example.com/doc/accounting/invoices.html>`_ and to
+`Send a pro-forma invoice <https://example.com/doc/sales/proforma.html>`_.
+
+.. _contributing/download:
+
+The ``download`` directive
+--------------------------
+
+The ``download`` directive allows referencing files (that are not necessarily :abbr:`RST
+(reStructuredText)` documents) within the source tree to be downloaded.
+
+Example
+~~~~~~~
+
+RST
+***
+
+.. code-block:: rst
+
+   Download this :download:`module structure template <extras/my_module.zip>` to start building your
+   module in no time.
+
+Render
+******
+
+Download this `module structure template <https://example.com/doc/odoosh/extras/my_module.zip>`_ to
+start building your module in no time.
+
+.. _contributing/image:
+
+The ``image`` directive
+-----------------------
+
+The ``image`` directive allows inserting images in a document. It comes with a set of optional
+parameter directives that can individually be omitted if considered redundant.
+
+Example
+~~~~~~~
+
+RST
+***
+
+.. code-block:: rst
+
+   .. image:: media/create_invoice.png
+      :align: center
+      :alt: Create an invoice
+      :height: 100
+      :width: 200
+      :scale: 50
+      :class: img-thumbnail
+      :target: ../invoicing.html#create-an-invoice
+
+Render
+******
+
+.. image:: media/create-invoice.png
+   :align: center
+   :alt: Create an invoice
+   :height: 100
+   :width: 200
+   :scale: 50
+   :class: img-thumbnail
+   :target: https://example.com/doc/sales/invoicing.html#create-an-invoice
+
+.. _contributing/admonitions:
+
+Admonitions (alert blocks)
+==========================
+
+.. _contributing/seealso:
+
+Seealso
+-------
+
+RST
+~~~
+
+.. code-block:: rst
+
+   .. seealso::
+      - :doc:`customer_invoices`
+      - `Pro-forma invoices <../sales/invoicing/proforma.html#activate-the-feature>`_
+
+Render
+~~~~~~
+
+.. seealso::
+   - `Customer invoices <https://example.com/doc/accounting/invoices.html>`_
+   - `Pro-forma invoices <https://example.com/doc/sales/proforma.html#activate-the-feature>`_
+
+.. _contributing/note:
+
+Note
+----
+
+RST
+~~~
+
+.. code-block:: rst
+
+   .. note::
+      Use this to get the attention of the reader about additional information.
+
+Render
+~~~~~~
+
+.. note::
+   Use this to get the attention of the reader about additional information.
+
+.. _contributing/tip:
+
+Tip
+---
+
+RST
+~~~
+
+.. code-block:: rst
+
+   .. tip::
+      Use this to inform the reader about a useful trick that requires an
+      action.
+
+Render
+~~~~~~
+
+.. tip::
+   Use this to inform the reader about a useful trick that requires an
+   action.
+
+.. _contributing/important:
+
+Important
+---------
+
+RST
+~~~
+
+.. code-block:: rst
+
+   .. important::
+      Use this to notify the reader about an important information.
+
+Render
+~~~~~~
+
+.. important::
+   Use this to notify the reader about an important information.
+
+.. _contributing/warning:
+
+Warning
+-------
+
+RST
+~~~
+
+.. code-block:: rst
+
+   .. warning::
+      Use this to require the reader to proceed with caution with what is
+      described in the warning.
+
+Render
+~~~~~~
+
+.. warning::
+   Use this to require the reader to proceed with caution with what is
+   described in the warning.
+
+.. _contributing/danger:
+
+Danger
+------
+
+RST
+~~~
+
+.. code-block:: rst
+
+   .. danger::
+      Use this to alarm the reader about a serious threat.
+
+Render
+~~~~~~
+
+.. danger::
+   Use this to alarm the reader about a serious threat.
+
+.. _contributing/formatting-tips:
+
+Formatting tips
+===============
+
+.. _contributing/line-break:
+
+Break the line but not the paragraph
+------------------------------------
+
+RST
+~~~
+
+.. code-block:: rst
+
+   | First super long line that you break in two…
+     here is rendered as a single line.
+   | Second line that follows a line break.
+
+Render
+~~~~~~
+
+| First super long line that you break in two…
+  here is rendered as a single line.
+| Second line that follows a line break.
+
+.. _contributing/comments:
+
+Add comments
+------------
+
+If you made a particular choice of writing or formatting that a future writer should be able to
+understand and take into account, consider writing a comment. Comments are blocks of text that do
+not count as a part of the documentation and that are used to pass a message to writers of the
+source code. They consist of a line starting with two dots and a space, followed by the comment.
+
+``.. For instance, this line will not be rendered in the documentation.``
+
+.. _contributing/tables:
+
+Use tables
+----------
+
+Make use of `this convenient table generator <https://www.tablesgenerator.com/text_tables>`_ to
+build your tables. Then, copy-paste the generated formatting into your document.
+
+.. _contributing/specialized-directives:
+
+Spice your writing with specialized directives
+----------------------------------------------
+
+Use these additional directives to fine-tune your content:
+
++-------------------+------------------------------------------+-------------------------------------------------------------------------------------------------------------------+
+| **Directive**     | **Purpose**                              | **Example**                                                                                                       |
+|                   |                                          +-----------------------------------------------------------+-------------------------------------------------------+
+|                   |                                          | **RST**                                                   | **HTML**                                              |
++-------------------+------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------+
+| ``abbr``          | Self-defining abbreviations              | ``:abbr:`SO (Sales Order)```                              | :abbr:`SO (Sales Order)`                              |
++-------------------+------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------+
+| ``command``       | Highlight a command                      | ``:command:`python example.py```                          | :command:`python example.py`                          |
++-------------------+------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------+
+| ``dfn``           | Define a term                            | ``:dfn:`a definition for a new term```                    | :dfn:`a definition for a new term`                    |
++-------------------+------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------+
+| ``file``          | Indicate a file path                     | ``:file:`~/odoo/odoo-bin```                               | :file:`~/odoo/odoo-bin`                               |
++-------------------+------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------+
+| ``menuselection`` | Guide a user through a sequence of menus | ``:menuselection:`Sales --> Configuration --> Settings``` | :menuselection:`Sales --> Configuration --> Settings` |
++-------------------+------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------+
+
+.. _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 case such as :ref:`hyperlink references
+<contributing/hyperlink-references>`, using backslashes for escaping is no longer an option because
+the outer backticks interpret enclosed backslashes and thus prevent them from escaping inner
+backticks. For instance, ```\`this formatting\```` produces an ``[UNKNOWN NODE title_reference]``
+error. Instead, `````this formatting````` should be used to produce the following result:
+```this formatting```.

practical.rst

@@ -13,3 +13,4 @@ Practical Information
    portal/my_odoo_portal
    support
    legal
+   contributing

requirements.txt

@@ -0,0 +1,2 @@
+Sphinx>=2.4.0
+Werkzeug==0.14.1