diff --git a/_extensions/odoo/__init__.py b/_extensions/odoo/__init__.py
index e02deaaff..e3473c996 100644
--- a/_extensions/odoo/__init__.py
+++ b/_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):
diff --git a/_extensions/odoo/layout.html b/_extensions/odoo/layout.html
index d2c155ac4..9b4028883 100644
--- a/_extensions/odoo/layout.html
+++ b/_extensions/odoo/layout.html
@@ -1,11 +1,11 @@
{% extends "basic/layout.html" %}
-
-{% set script_files = script_files + [
-'_static/jquery.min.js',
-'_static/bootstrap.js',
-'_static/doc.js',
-'_static/jquery.noconflict.js',
-] %}
+{%- block scripts %}
+ {{ super() }}
+
+
+
+
+{%- endblock %}
{% set classes = [] %}
{% if pagename == master_doc %}
diff --git a/_extensions/odoo/pycompat.py b/_extensions/odoo/pycompat.py
deleted file mode 100644
index 804a2a0ba..000000000
--- a/_extensions/odoo/pycompat.py
+++ /dev/null
@@ -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)
-
diff --git a/_extensions/odoo/translator.py b/_extensions/odoo/translator.py
index 769496f8a..beac304ff 100644
--- a/_extensions/odoo/translator.py
+++ b/_extensions/odoo/translator.py
@@ -2,19 +2,12 @@
import os.path
import posixpath
import re
-import urllib
from docutils import nodes
-from sphinx import addnodes, util
+from sphinx import addnodes, util, builders
from sphinx.locale import admonitionlabels
-from . import pycompat
-
-try:
- from urllib import url2pathname
-except ImportError:
- # P3
- from urllib.request import url2pathname
+from urllib.request import url2pathname
def _parents(node):
@@ -45,6 +38,11 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
]
def __init__(self, builder, document):
+ # order of parameter swapped between Sphinx 1.x and 2.x, check if
+ # we're running 1.x and swap back
+ if not isinstance(builder, builders.Builder):
+ builder, document = document, builder
+
super(BootstrapTranslator, self).__init__(document)
self.builder = builder
self.body = []
@@ -58,6 +56,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 +66,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'<',
ord('"'): u'"',
@@ -76,7 +75,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 +110,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 +431,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 +651,7 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
self.body.append(title if title else util.nodes.clean_astext(env.titles[ref]))
self.body.append(u'')
- 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'])
diff --git a/_static/banners/contributing.png b/_static/banners/contributing.png
new file mode 100644
index 000000000..88b38f11b
Binary files /dev/null and b/_static/banners/contributing.png differ
diff --git a/contributing.rst b/contributing.rst
new file mode 100644
index 000000000..d0931edb8
--- /dev/null
+++ b/contributing.rst
@@ -0,0 +1,10 @@
+:banner: banners/contributing.png
+
+============
+Contributing
+============
+
+.. toctree::
+ :titlesonly:
+
+ contributing/documentation
\ No newline at end of file
diff --git a/contributing/documentation.rst b/contributing/documentation.rst
new file mode 100644
index 000000000..e91e241a9
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/contributing/documentation/guidelines.rst b/contributing/documentation/guidelines.rst
new file mode 100644
index 000000000..6e890126e
--- /dev/null
+++ b/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.
diff --git a/contributing/documentation/introduction_guide.rst b/contributing/documentation/introduction_guide.rst
new file mode 100644
index 000000000..4986aa594
--- /dev/null
+++ b/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
+ `_ of Odoo. The documentation for `developing
+ in Odoo `_ in maintained alongside the
+ source code of Odoo at `github.com/odoo/odoo `_.
+
+.. _contributing/rst-intro:
+
+reStructuredText
+================
+
+Our documentation is written in **reStructuredText** (RST), a `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
+` 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 ` 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
+`_ 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
+ `_), 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 `.
+
+#. 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 `_ 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
+ `_.
+#. 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 `_. 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 `_ 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 `_.
+and is written in `Python `_. 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
+`_. 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 `_ 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
+ `_.
+
+.. _contributing/pngquant:
+
+pngquant
+~~~~~~~~
+
+`pngquant `_ 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
+ `_.
+
+.. _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
+`_ 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 `.
+
+.. 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 `_ and `this
+ interactive tutorial `_.
+
+#. 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
+ `_ 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/
diff --git a/contributing/documentation/media/commit-changes.png b/contributing/documentation/media/commit-changes.png
new file mode 100644
index 000000000..f020ac025
Binary files /dev/null and b/contributing/documentation/media/commit-changes.png differ
diff --git a/contributing/documentation/media/compare-across-forks.png b/contributing/documentation/media/compare-across-forks.png
new file mode 100644
index 000000000..36dd14806
Binary files /dev/null and b/contributing/documentation/media/compare-across-forks.png differ
diff --git a/contributing/documentation/media/create-invoice.png b/contributing/documentation/media/create-invoice.png
new file mode 100644
index 000000000..b02b2c288
Binary files /dev/null and b/contributing/documentation/media/create-invoice.png differ
diff --git a/contributing/documentation/media/create-pull-request.png b/contributing/documentation/media/create-pull-request.png
new file mode 100644
index 000000000..fa559c7e0
Binary files /dev/null and b/contributing/documentation/media/create-pull-request.png differ
diff --git a/contributing/documentation/media/edit-on-github.png b/contributing/documentation/media/edit-on-github.png
new file mode 100644
index 000000000..a1fa44351
Binary files /dev/null and b/contributing/documentation/media/edit-on-github.png differ
diff --git a/contributing/documentation/media/fork-button.png b/contributing/documentation/media/fork-button.png
new file mode 100644
index 000000000..9b7179288
Binary files /dev/null and b/contributing/documentation/media/fork-button.png differ
diff --git a/contributing/documentation/media/fork-repository.png b/contributing/documentation/media/fork-repository.png
new file mode 100644
index 000000000..af76cafa7
Binary files /dev/null and b/contributing/documentation/media/fork-repository.png differ
diff --git a/contributing/documentation/media/new-pull-request.png b/contributing/documentation/media/new-pull-request.png
new file mode 100644
index 000000000..158055cef
Binary files /dev/null and b/contributing/documentation/media/new-pull-request.png differ
diff --git a/contributing/documentation/media/select-branches-base.png b/contributing/documentation/media/select-branches-base.png
new file mode 100644
index 000000000..efd6ac1c1
Binary files /dev/null and b/contributing/documentation/media/select-branches-base.png differ
diff --git a/contributing/documentation/media/select-branches-fork.png b/contributing/documentation/media/select-branches-fork.png
new file mode 100644
index 000000000..4305e2f91
Binary files /dev/null and b/contributing/documentation/media/select-branches-fork.png differ
diff --git a/contributing/documentation/media/version-selector.png b/contributing/documentation/media/version-selector.png
new file mode 100644
index 000000000..ba478332c
Binary files /dev/null and b/contributing/documentation/media/version-selector.png differ
diff --git a/contributing/documentation/rst_cheat_sheet.rst b/contributing/documentation/rst_cheat_sheet.rst
new file mode 100644
index 000000000..d391d363d
--- /dev/null
+++ b/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 `_``
+
+.. 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
+`_.`` is rendered as follows in HTML: “For instance, `this is a hyperlink
+reference `_.”
+
+.. _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 `_`` 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 `_ is a common abbreviation.
+
+Render
+******
+
+A `proof-of-concept `_ is a simplified version, a
+prototype of what is expected to agree on the main lines of expected changes. `PoC
+`_ is a common abbreviation.
+
+.. _contributing/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 ``` 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
+ `.
+
+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 `, ...
+
+Render
+******
+
+This can easily be done by creating a new product, see `How to create a product?
+`_ for additional help.
+
+**How to create a product?**
+
+As explained at the `start of the page `_, ...
+
+.. _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?
+`_ 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 ``` creates a hyperlink reference to the documentation page with
+ the given label.
+
+Example
+~~~~~~~
+
+RST
+***
+
+.. code-block:: rst
+
+ Please refer to :doc:`this documentation ` and to
+ :doc:`../sales/invoicing/proforma`.
+
+Render
+******
+
+Please refer to `this documentation `_ and to
+`Send a pro-forma invoice `_.
+
+.. _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 ` to start building your
+ module in no time.
+
+Render
+******
+
+Download this `module structure template `_ 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 `_
+ - `Pro-forma invoices `_
+
+.. _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 `_ 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
+`, using backslashes for escaping is no longer an option because
+the outer backticks interpret enclosed backslashes and thus prevent them from escaping inner
+backticks. For instance, ```\`this formatting\```` produces an ``[UNKNOWN NODE title_reference]``
+error. Instead, `````this formatting````` should be used to produce the following result:
+```this formatting```.
diff --git a/practical.rst b/practical.rst
index 83efa5e11..46b35d221 100644
--- a/practical.rst
+++ b/practical.rst
@@ -13,3 +13,4 @@ Practical Information
portal/my_odoo_portal
support
legal
+ contributing
diff --git a/requirements.txt b/requirements.txt
index 71121d994..95726293f 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1 +1,2 @@
-Sphinx<2
\ No newline at end of file
+Sphinx>=2.4.0
+Werkzeug==0.14.1
\ No newline at end of file
diff --git a/support.rst b/support.rst
index 6580fba93..83164ef8e 100644
--- a/support.rst
+++ b/support.rst
@@ -10,4 +10,3 @@ Support
support/where_can_i_get_support
support/what_can_i_expect
support/supported_versions
- support/user_doc
diff --git a/support/user_doc.rst b/support/user_doc.rst
deleted file mode 100644
index 112445751..000000000
--- a/support/user_doc.rst
+++ /dev/null
@@ -1,152 +0,0 @@
-.. :banner: banners/support.png
-
-
-===============================
-Contribute to the documentation
-===============================
-
-First of all...
-===============
-
-**... Thank you for landing here and helping us to improve the user documentation of Odoo.**
-
-
-Edit an existing page
-=====================
-
-#. As our documentation is maintained on GitHub, you'll need a free `GitHub account
- `_.
-#. Pick a page in our :doc:`user documentation <../index>`.
- **Please take care of selecting the right version of Odoo.**
-#. Click on **Edit on Github** in the left menu.
-
- .. image:: ./media/edit_on_github.png
- :align: center
- :alt: Click on "Edit on Github".
-
-#. If this is the first time you edit our documentation, click on **Fork repository**, otherwise
- you won't see this step.
-#. Use Github's editor to add your text. Text is tagged with a simple syntax called `RST
- `_. Don't worry, it's not so hard to learn 🤓...
- See the following section of this document for a quick overview of RST commands.
-
- .. image:: ./media/add_text.png
- :align: center
- :alt: Use Github's editor to add your text.
-
-#. Click on **Preview changes** to review your contribution in a human-readable format.
-
- .. image:: ./media/preview_changes.png
- :align: center
- :alt: Click on "Preview changes" to review your contribution.
-
-#. In the **Propose file change** section, add a short title to your contribution.
- The title should summarize your changes. You may use the second box to add an extended
- description if your contribution requires a longer explanation.
-
- .. image:: ./media/propose_changes.png
- :align: center
- :alt: Add a title and submit your contribution.
-
-#. Submit your contribution by clicking on **Propose file change**.
-#. Click on **Create pull request**.
-#. Wait for an Odoo maintainer to add your contribution. Thank you for your help!
-
-.. warning::
- There is no automatic port of your edit to another version of the documentation.
-
- If your change should apply to multiple versions of Odoo, please warn us in your contribution message.
-
-
-RST Cheat Sheet
----------------
-
-.. TODO merge with our internal tutorial : https://docs.google.com/document/d/19QkK9zDpoHJ57QtBgAs0sjInfO8zR_3mfCIr-CxS85Y/
-
-Here is a summary of the markup elements you may use while editing our documentation.
-
-+------------------------------+--------------------------+---------------------------------------+
-| Code | Display | Comments |
-+==============================+==========================+=======================================+
-| .. code-block:: rst | Text in *italics* | |
-| | | |
-| Text in *italics* | | |
-+------------------------------+--------------------------+---------------------------------------+
-| .. code-block:: rst | Text in **bold** letters | |
-| | | |
-| Text in **bold** letters | | |
-+------------------------------+--------------------------+---------------------------------------+
-| .. code-block:: rst | 1. Numbered | - Must be surrounded by white lines. |
-| | 2. Bullet | |
-| 1. Numbered | 3. List | |
-| 2. Bullet | | |
-| 3. List | | |
-+------------------------------+--------------------------+---------------------------------------+
-| .. code-block:: rst | - Numbered | - Must be surrounded by white lines. |
-| | - Bullet | |
-| - Bullet | - List | |
-| - Point | | |
-| - List | | |
-+------------------------------+--------------------------+---------------------------------------+
-| .. code-block:: rst | This is `a hyper link | - Here is `how to enter backticks |
-| | `_.| on your keyboard |
-| This is `a hyper link | | `_. |
-| `_. | | - Don't forget terminal *underscore*. |
-+------------------------------+--------------------------+---------------------------------------+
-
-
-.. note::
- There are many more commands available, see `comprehensive documentation
- `_ of RST.
-
-
-Add images to your documents
-============================
-
-
-.. warning::
- This procedure is possible only for users who have **push** access on the documentation repository (eg: mainly, Odoo maintainers).
- We are working on improving this.
-
-1. First of all, prepare your screenshots.
-
- - They must be good-quality PNG images.
- - Crop your screenshots to display only the relevant part of the screen. Large screenshots are hard
- to read and don't display well in a documentation.
- - Always take your screenshots on a demo instance of Odoo; **never** include any personal data.
-
-2. Upload them to the ``media/`` directory which is located next to the page you are editing. If the directory does not exist, create it.
-3. When editing your page, use this code piece in order to load your image:
-
- .. code-block:: rst
-
- .. image:: ./media/your_image_file.png
- :align: center
- :alt: Text that is displayed when your image is not available (eg: for screen readers and other accessibility tools)
-
-4. Submit your changes
-
-
-.. Add a page about a new topic
-.. ============================
-
-.. TODO publish our internal tutorial : https://docs.google.com/document/d/1EP32VFjN08piZoGn1BXT6ZOVb5AKUTieeeuK10nxZz8/
-
-
-Technical Details for Nerds
-===========================
-
-Advanced users may, of course, fork and clone the `GitHub repository `_.
-Then submit a pull request with the canonical Git/GitHub workflow.
-
-See our `README `_ file about building
-the documentation.
-
-
-Developer documentation
-=======================
-
-Documentation that targets developers of Odoo apps is maintained alongside `the source code of Odoo `_.
-
-.. note::
- User documentation might contain technicalities yet, when they are related to configuration and everyday use of Odoo.