documentation/content/contributing/documentation.rst

:show-content:

===================
Write documentation
===================

.. toctree::
   :titlesonly:

   documentation/content_guidelines
   documentation/rst_cheat_sheet
   documentation/rst_guidelines

**First of all, thank you for landing here and helping us improve the user documentation of Odoo!**

This introductory guide will help you acquire the tools and knowledge you need to write
documentation, whether you plan to make a minor content change or document an application from
scratch.

.. _contributing/rst-intro:

reStructuredText
================

Our documentation is written in **reStructuredText** (RST), a `lightweight markup language
<https://en.wikipedia.org/wiki/Lightweight_markup_language>`_ consisting of normal text augmented
with markup which allows including headings, images, notes, and so on. This might seem a bit
abstract but there is no need to worry. :abbr:`RST (reStructuredText)` is not hard to learn,
especially if you intend to make only small changes to the content.

If you need to learn about a specific markup, head over to :doc:`our cheat sheet for RST
<documentation/rst_cheat_sheet>` which contains all the information that you should ever need for
the user documentation of Odoo.

.. important::
   We kindly ask you to observe a set of :doc:`content <documentation/content_guidelines>` and
   :doc:`RST <documentation/rst_guidelines>` guidelines as you write documentation. This ensures
   that you stay consistent with the rest of the documentation and facilitates the approval of your
   content changes as they are reviewed by a redactor at Odoo.

.. seealso::
   - :doc:`documentation/content_guidelines`
   - :doc:`documentation/rst_cheat_sheet`
   - :doc:`documentation/rst_guidelines`

.. _contributing/getting-started:

Getting started
===============

As our documentation is maintained on GitHub, you will need a free GitHub account. Click `here
<https://github.com/join>`_ to create one.

Now, depending on whether you want to update existing content, or rather work on new content and
make file changes, you have two courses of action:

#. **For small changes** in ``.rst`` files only, i.e. addition/edition of paragraphs or typos, **we
   suggest that you use the GitHub interface**. This is the easiest and fasted way to submit your
   request for changes for the documentation and is suitable for non-technical people. Read
   :ref:`contributing/github-interface` to learn how to use this method.
#. **For more complex cases**, it is necessary to **use Git and work from a local copy of the
   documentation**. This method seems intimidating but only requires basic knowledge of Git. See
   :ref:`contributing/canonical-git-workflow` for more information on this method.

.. _contributing/github-interface:

Use the GitHub interface
========================

#. Verify that you are browsing the documentation in the version that you intend to change. The
   version can be selected from the dropdown in the top menu.

   .. image:: documentation/version-selector.png

#. Head over to the page that you want to change and click on the **Edit on GitHub** button in the
   bottom of the left menu.

   .. image:: documentation/edit-on-github.png

#. If you do not have edit rights on the repository (`odoo/documentation
   <https://github.com/odoo/documentation>`_), you need to fork it by clicking on the appropriate
   button. In other terms, you create a copy of the entire repository on your own account. If you do
   have the edit rights, skip this step.

   .. image:: documentation/fork-repository.png

#. Make the appropriate changes while taking care of following the :doc:`content
   <documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>` guidelines.

#. Click on the **Preview changes** button to review your contribution in a more human-readable
   format. Be aware that the preview is not able to handle all markups correctly. Notes and tips,
   for instance, are not correctly rendered. The version of your content published to the website
   will be, however.

#. Go to the bottom of the page to create a commit (:dfn:`what packs your changes together and
   labels them with a commit message`) of your changes.

   #. | In first text box, describe your changes. For instance, "Fix a typo" and "Add documentation
        for invoicing of sales orders" are two clear commit messages.
      | In the second text box, justify *why* you made these changes, if you feel that it is not
        obvious.
   #. Select the option "Create a new branch for this commit and start a pull request." if you have
      the choice (if you have partial or full edit writes on the repository). If not, skip this
      step.
   #. Click on the green button. It is either labelled "Commit changes" or "Propose file change".

   .. image:: documentation/commit-changes.png

#. In the dropdown for the selection of the base branch (i.e., the version of the documentation that
   your changes concern), make sure to select the same version as in the first step of this guide
   and click on the **Create pull request** button.

   .. image:: documentation/select-branches-base.png

#. Double-check your :abbr:`PR (Pull Request)` and, when ready, click again on the **Create pull
   request** button to submit your changes for review by a content writer at Odoo.

   .. image:: documentation/create-pull-request.png

#. You're done! If your changes are approved straight away they will appear in the documentation the
   very next day. It may also be the case that the reviewer has a question or a remark, so make sure
   to check your notifications or your emails, depending on your account settings.

.. _contributing/canonical-git-workflow:

Use the canonical Git workflow
==============================

.. _contributing/prepare-machine:

Prepare your machine
--------------------

.. _contributing/install-git:

Install Git
~~~~~~~~~~~

We use `Git <https://en.wikipedia.org/wiki/Git>`_ to manage the files of the user documentation.
It is a tool that allows to track the history of changes made to a file and, more importantly, to
work on different versions of those files at the same time. It means that you do not need to worry
about overwriting someone else’s pending work when you start editing the documentation.

You must then configure Git to identify yourself as the author of your future contribution. Enter
the same email address as the one you used to register on GitHub.

#. Download and install **Git** on your machine.
#. Verify that `the installation folder of Git is included in your system's PATH variable
   <win-add-to-path_>`_.
#. Execute the following commands in a terminal:

   .. code-block:: console

      $ git config --global user.name “Your Name”
      $ git config --global user.email “youremail@example.com”

.. _contributing/fetch-sources:

Fetch the sources
~~~~~~~~~~~~~~~~~

As stated earlier, our documentation (in all its versions) is maintained on GitHub at
`github.com/odoo/documentation <https://github.com/odoo/documentation>`_. A modification is made by
the mean of a :abbr:`PR (Pull Request)` (:dfn:`proposal of content changes`) to allow for a review
of the changes before updating the sources of the documentation.

Prior to submitting a modification, you need to make a copy of the sources and download that copy on
your machine.

#. Go to `github.com/odoo/documentation <https://github.com/odoo/documentation>`_ and click on the
   **Fork** button in the top right corner.

   .. image:: documentation/fork-button.png

#. Execute the following commands in a terminal:

   .. code-block:: console

      $ git clone https://github.com/odoo/documentation
      $ cd documentation/

   .. important::
      If you do not have edit rights on the repository owned by Odoo, replace "odoo" with your
      Github username in the URL of the command above. If you do have edit rights, it is not
      necessary to fork the repository.

#. In order to ease the collaboration between writers coming from many different systems and teams,
   execute the following group of commands that correspond to your :abbr:`OS (Operating System)` in
   a terminal.

   - Windows:

     .. code-block:: doscon

        $ cd documentation/
        $ git config --global core.autocrlf true
        $ git config commit.template %CD%\commit_template.txt

   - Linux or Mac OS:

     .. code-block:: console

        $ cd documentation/
        $ git config --global core.autocrlf input
        $ git config commit.template `pwd`/commit_template.txt

.. _contributing/python:

Python
~~~~~~

Because the documentation is written in :abbr:`RST (reStructuredText)`, it needs to be built
(:dfn:`converted to HTML`) in order to display nicely. This is done by the documentation generator
which takes the original :abbr:`RST (reStructuredText)` files as input, transforms the markups
in a human-readable format, and outputs HTML files to be read in your web browser.

The documentation generator that we use is called `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
and is written in `Python <https://en.wikipedia.org/wiki/Python_(programming_language)>`_. You have
to install Python in order to use Sphinx. For the record, Sphinx is the program and Python the
programming language, but you do not need to know much more about them so don't panic!

Python comes with its own package manager: `pip
<https://en.wikipedia.org/wiki/Pip_(package_manager)>`_. It allows installing Python dependencies in
a single command.

#. Download and install the recommended release (`see README file
   <https://github.com/odoo/documentation/tree/12.0/README.md>`_) of **Python 3** on your machine.
#. Make sure to have **pip** installed on your machine (on Windows, you can install pip alongside
   Python).
#. Execute the following commands in a terminal to verify that both installations finished
   successfully:

   .. code-block:: console

      $ python3 --version
      $ pip3 --version

#. Execute the following commands in a terminal to install the Python dependencies of the
   documentation:

   .. code-block:: console

      $ cd documentation/
      $ pip3 install -r requirements.txt

.. note::
   Depending on your :abbr:`OS (Operating System)`, you may need to run the commands ``python`` and
   ``pip`` instead of ``python3`` and ``pip3``

.. _contributing/make:

Make
~~~~

`Make <https://en.wikipedia.org/wiki/Make_(software)>`_ is a tool that packs a bunch of
command-lines into one to be easier to remember and to type. In our case, it is used to execute
complex Sphinx build commands by using a single and simpler one instead.

#. Download and install **Make** on your machine.
#. Verify that `the installation folder of Make is included in your system's PATH variable
   <win-add-to-path_>`_.

.. _contributing/pngquant:

pngquant
~~~~~~~~

`pngquant <https://pngquant.org/>`_ is a tool that we use to compress PNG images so that the
documentation does not end up weighting several Gigabytes in a few year span.

#. Download and install **pngquant** on your machine.
#. Verify that `the installation folder of pngquant is included in your system's PATH variable
   <win-add-to-path_>`_.

.. _contributing/prepare-version:

Prepare your version
--------------------

Now that your machine is all set up, it is time to do the same for your version of the documentation
files. As it would not be convenient to have several people working on the version 13.0 in parallel
(conflicts of content would occur all the time), and in order to be able to create a :abbr:`PR
(Pull Request)`, you must `create a new branch
<https://www.atlassian.com/git/tutorials/using-branches>`_ starting from the branch 13.0. In other
words, you copy the entirety of this version’s files and give it another name. For this example, we
will go with ``13.0-my_contribution``.

Execute the following commands in a terminal to...

#. Navigate to the documentation folder:

   .. code-block:: console

      $ cd documentation/

#. Switch to the version 13.0:

   .. code-block:: console

      $ git checkout 13.0

#. Create your own branch which will be a copy of 13.0:

   .. code-block:: console

      $ git checkout -b 13.0-my_contribution

.. _contributing/perform-changes:

Perform your changes
--------------------

You can now perform any change you want to the documentation files. These changes must be compliant
with :abbr:`RST (reStructuredText)` syntax (see :doc:`documentation/rst_cheat_sheet`) and with our
:doc:`content <documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>`
guidelines.

.. important::
   If your changes include the addition of a new image, for instance :file:`my_image.png`, proceed
   as follows:

   #. Make sure that the image is in ``.png`` format.
   #. Execute the following commands in a terminal:

      .. code-block:: console

         $ cd path-to-the-directory-of-the-image/
         $ pngquant my_image.png

   #. Delete :file:`my_image.png`.
   #. Rename :file:`my_image-fs8.png` to :file:`my_image.png`.

.. _contributing/preview-changes:

Preview your changes
--------------------

To preview your changes in a generated documentation, proceed as follows:

#. Execute the following commands in a terminal:

   .. code-block:: console

      $ cd documentation/
      $ make clean
      $ make html

   .. tip::
      You can omit the :command:`make clean` command when no recent change has been made to the
      hierarchy of documentation files.

#. Fix any error or warning shown in the logs of the build.
#. Open the file :file:`documentation/_build/html/index.html` with your default web browser.

.. note::
   These steps have for only purpose to show you the final results of your changes. They have no
   impact on the documentation source files.

.. _contributing/submit-changes:

Submit your changes
-------------------

.. important::
   We expect you to have basic knowledge of Git, which should be enough to cover the basic flow of a
   one-time contribution. If you plan on submitting several contributions, work on older versions of
   the documentation or perform any other advanced action, we recommend you to be confident with
   Git. Help yourself with `this manual of Git <https://www.atlassian.com/git>`_ and `this
   interactive tutorial <https://learngitbranching.js.org/>`_.

#. Execute the following commands in a terminal:

   .. code-block:: console

      $ git add *
      $ git commit
      $ git push -u origin 13.0-my_contribution

#. Go to `github.com/odoo/documentation/pulls
   <https://github.com/odoo/documentation/pulls>`_ and click on the **New pull request** button.

   .. image:: documentation/new-pull-request.png

#. If you forked the base repository in the section :ref:`contributing/fetch-sources`, click on the
   link **compare across forks** If not, skip this step.

   .. image:: documentation/compare-across-forks.png

#. In the dropdown for the selection of the base branch (i.e., the version of the documentation that
   your changes concern), make sure to select the version that your changes target (here **13.0**).

   .. image:: documentation/select-branches-fork.png

#. Double-check your :abbr:`PR (Pull Request)` and, when ready, click again on the **Create pull
   request** button to submit your changes for review by a redactor at Odoo.

   .. image:: documentation/create-pull-request.png

#. You're done! If your changes are approved straight away they will appear in the documentation the
   very next day. It may also be the case that the reviewer has a question or a remark, so make sure
   to check your notifications or your emails, depending on your account settings.


.. _win-add-to-path: https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/