301 lines
13 KiB
ReStructuredText
301 lines
13 KiB
ReStructuredText
:show-content:
|
|
|
|
=============
|
|
Documentation
|
|
=============
|
|
|
|
.. toctree::
|
|
:titlesonly:
|
|
|
|
documentation/content_guidelines
|
|
documentation/rst_guidelines
|
|
|
|
This introductory guide will help you acquire the tools and knowledge needed to contribute to the
|
|
documentation.
|
|
|
|
Read the :ref:`introduction to the reStructuredText language <contributing/documentation/rst-intro>`
|
|
if you are not familiar with it. Then, there are two courses of action to start contributing to the
|
|
documentation:
|
|
|
|
- **For minor changes**, such as adding a paragraph or fixing a typo, we recommend **using the
|
|
GitHub interface**. This is the easiest and fastest way to submit changes, and it is suitable for
|
|
non-technical people. Jump directly to the :ref:`contributing/documentation/first-contribution`
|
|
section to get started.
|
|
- **For more complex changes**, such as adding a new page, it is necessary to **use Git** and work
|
|
from a local copy of the documentation. Follow the instructions in the
|
|
:ref:`contributing/documentation/setup` section first to prepare your environment.
|
|
|
|
.. seealso::
|
|
:doc:`Discover other ways to contribute to Odoo <../contributing>`
|
|
|
|
.. _contributing/documentation/rst-intro:
|
|
|
|
reStructuredText (RST)
|
|
======================
|
|
|
|
The documentation is written in **reStructuredText** (RST), a `lightweight markup language
|
|
<https://en.wikipedia.org/wiki/Lightweight_markup_language>`_ consisting of regular text augmented
|
|
with markup, which allows including headings, images, notes, and so on. :abbr:`RST
|
|
(reStructuredText)` is easy to use, even if you are not familiar with it.
|
|
|
|
.. important::
|
|
Be mindful of our :doc:`content <documentation/content_guidelines>` and
|
|
:doc:`RST <documentation/rst_guidelines>` guidelines as you write documentation. This ensures
|
|
that the documentation stays consistent and facilitates the approval of changes by the Odoo team.
|
|
|
|
.. _contributing/documentation/setup:
|
|
|
|
Environment setup
|
|
=================
|
|
|
|
The instructions below help you prepare your environment for making local changes to the
|
|
documentation and then push them to GitHub. Skip this section and go to
|
|
:ref:`contributing/documentation/first-contribution` if you have already completed this step or want
|
|
to make changes from the GitHub interface.
|
|
|
|
#. First, `create a GitHub account <https://github.com/join>`_. Odoo uses GitHub to manage the
|
|
source code of its products, and this is where you will submit your changes.
|
|
#. `Generate a new SSH key and register it on your GitHub account
|
|
<https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_.
|
|
#. Go to `github.com/odoo/documentation <https://github.com/odoo/documentation>`_ and click on the
|
|
:guilabel:`Fork` button in the top right corner to create a fork (:dfn:`your own copy`) of the
|
|
repository on your account. This creates a copy of the codebase to which you can make changes
|
|
without affecting the main codebase. Skip this step if you work at Odoo.
|
|
#. .. include:: install_git.rst
|
|
#. Configure Git to identify yourself as the author of your future contributions. Enter the same
|
|
email address you used to register on GitHub.
|
|
|
|
.. code-block:: console
|
|
|
|
$ git config --global user.name "Your Name"
|
|
$ git config --global user.email "youremail@example.com"
|
|
|
|
#. Clone the sources with Git and navigate into the local repository.
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone git@github.com:odoo/documentation.git
|
|
$ cd documentation
|
|
|
|
#. Configure Git to push changes to your fork rather than to the main codebase. In the commands
|
|
below, replace `<your_github_account>` with the name of the GitHub account on which you created
|
|
the fork. Skip this step if you work at Odoo.
|
|
|
|
.. code-block:: console
|
|
|
|
$ git remote add dev git@github.com:<your_github_account>/documentation.git
|
|
|
|
#. Configure Git to ease the collaboration between writers coming from different systems.
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux and macOS
|
|
|
|
.. code-block:: console
|
|
|
|
$ git config --global core.autocrlf input
|
|
$ git config commit.template `pwd`/commit_template.txt
|
|
|
|
.. group-tab:: Windows
|
|
|
|
.. code-block:: console
|
|
|
|
$ git config --global core.autocrlf true
|
|
$ git config commit.template %CD%\commit_template.txt
|
|
|
|
#. Install the latest release of `Python <https://wiki.python.org/moin/BeginnersGuide/Download>`_
|
|
and `pip <https://pip.pypa.io/en/stable/installation/>`_.
|
|
#. Install the Python dependencies of the documentation with pip.
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip install -r requirements.txt
|
|
|
|
Verify that the installation directory of the Python dependencies is included in your system's
|
|
`PATH` variable.
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux and macOS
|
|
|
|
Follow the `guide to update the PATH variable on Linux and macOS
|
|
<https://unix.stackexchange.com/a/26059>`_ with the installation path of the Python
|
|
dependencies (by default :file:`~/.local/bin`).
|
|
|
|
.. group-tab:: Windows
|
|
|
|
Follow the `guide to update the PATH variable on Windows
|
|
<https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/>`_
|
|
with the installation path of the Python dependencies.
|
|
|
|
#. Install Make.
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo apt install make -y
|
|
|
|
.. group-tab:: macOS
|
|
|
|
Follow the `guide to install Make on macOS <https://formulae.brew.sh/formula/make>`_
|
|
|
|
.. group-tab:: Windows
|
|
|
|
Follow the `guide to install Make on Windows
|
|
<https://www.technewstoday.com/install-and-use-make-in-windows>`_.
|
|
|
|
#. `Install pngquant <https://pngquant.org/>`_.
|
|
#. You are now ready to :ref:`make your first contribution
|
|
<contributing/documentation/first-contribution>` with Git.
|
|
|
|
.. _contributing/documentation/first-contribution:
|
|
|
|
Contributing to the documentation
|
|
=================================
|
|
|
|
.. tabs::
|
|
|
|
.. tab:: Contribute from the GitHub interface
|
|
|
|
#. First, `create a GitHub account <https://github.com/join>`_. Odoo uses GitHub to manage the
|
|
source code of its products, and this is where you will submit your changes.
|
|
#. Verify that you are browsing the documentation in the version that you intend to change.
|
|
The version can be selected from the dropdown in the top menu.
|
|
#. Head to the page that you want to change and click on the :guilabel:`Edit on GitHub` button
|
|
in the top right corner of the page.
|
|
#. Click on the :guilabel:`Fork this repository` button to create a fork (:dfn:`your own
|
|
copy`) of the repository on your account. This creates a copy of the codebase to which you
|
|
can make changes without affecting the main codebase. Skip this step if you work at Odoo.
|
|
|
|
.. image:: documentation/fork-repository.png
|
|
:scale: 60%
|
|
|
|
#. Make the desired changes while taking care of following the :doc:`content
|
|
<documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>`
|
|
guidelines.
|
|
|
|
.. tip::
|
|
Click on the :guilabel:`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 shown as plain text.
|
|
|
|
#. Scroll to the bottom of the page and fill out the small form to propose your changes. In
|
|
the first text box, write a very short summary of your changes. For instance, "Fix a typo"
|
|
or "Add documentation for invoicing of sales orders." In the second text box, explain *why*
|
|
you are proposing these changes. Then, click on the :guilabel:`Propose changes` button.
|
|
|
|
.. image:: documentation/propose-changes.png
|
|
:scale: 60%
|
|
|
|
#. Review your changes and click on the :guilabel:`Create pull request` button.
|
|
#. Tick the :guilabel:`Allow edits from maintainer` checkbox. Skip this step if you work at
|
|
Odoo.
|
|
#. Review the summary that you wrote about your changes and click on the :guilabel:`Create
|
|
pull request` button again.
|
|
#. At the bottom of the page, check the mergeability status and address any issues.
|
|
#. As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team
|
|
is automatically assigned for review. If the reviewer has questions or remarks, they will
|
|
post them as comments and you will be notified by email. Those comments must be resolved
|
|
for the contribution to go forward.
|
|
|
|
#. Once your changes are approved, the reviewer merges them and they appear online the next
|
|
day.
|
|
|
|
.. tab:: Contribute with Git
|
|
|
|
.. important::
|
|
Some steps of this guide require to be comfortable with Git. Here are some `tutorials
|
|
<https://www.atlassian.com/git/tutorials>`_ and an `interactive training
|
|
<https://learngitbranching.js.org/>`_ if you are stuck at some point.
|
|
|
|
Now that your environment is set up, you can start contributing to the documentation. In a
|
|
terminal, navigate to the directory where you cloned the sources and follow the guide below.
|
|
|
|
#. Choose the version of the documentation to which you want to make changes. Keep in mind
|
|
that contributions targeting an :doc:`unsupported version of Odoo
|
|
</administration/supported_versions>` are not accepted. This guide assumes that the changes
|
|
target the documentation of Odoo {CURRENT_VERSION}, which corresponds to branch
|
|
`{CURRENT_BRANCH}`.
|
|
#. Create a new branch starting from branch {CURRENT_BRANCH}. Prefix the branch name with the
|
|
base branch: `{CURRENT_BRANCH}-...`. If you work at Odoo, suffix the branch name with your
|
|
Odoo handle: `{CURRENT_BRANCH}-...-xyz`.
|
|
|
|
.. example::
|
|
|
|
.. code-block:: console
|
|
|
|
$ git switch -c {CURRENT_BRANCH}-explain-pricelists
|
|
|
|
.. code-block:: console
|
|
|
|
$ git switch -c {CURRENT_BRANCH}-explain-pricelists-xyz
|
|
|
|
#. Make the desired changes while taking care of following the :doc:`content
|
|
<documentation/content_guidelines>` and :doc:`RST <documentation/rst_guidelines>`
|
|
guidelines.
|
|
#. Compress all PNG images that were added or modified.
|
|
|
|
.. code-block:: console
|
|
|
|
$ pngquant path/to/image.png
|
|
$ mv path/to/image-fs8.png path/to/image.png
|
|
|
|
#. Write a `redirect rule
|
|
<https://github.com/odoo/documentation/tree/{BRANCH}/redirects/MANUAL.md>`_ for every RST
|
|
file that were renamed.
|
|
#. Build the documentation with :command:`make`. Then, open :file:`_build/index.html` in a web
|
|
browser to browse the documentation with your changes.
|
|
|
|
.. tip::
|
|
Use :command:`make help` to learn about other useful commands.
|
|
|
|
#. Commit your changes. Write a clear commit message as instructed in the :doc:`Git guidelines
|
|
<development/git_guidelines>`.
|
|
|
|
.. code-block:: console
|
|
|
|
$ git add .
|
|
$ git commit
|
|
|
|
#. Push your changes to your fork, for which we added the remote alias `dev`.
|
|
|
|
.. example::
|
|
|
|
.. code-block:: console
|
|
|
|
$ git push -u dev {CURRENT_BRANCH}-explain-pricelists
|
|
|
|
If you work at Odoo, push your changes directly to the main codebase whose remote alias is
|
|
`origin`.
|
|
|
|
.. example::
|
|
|
|
.. code-block:: console
|
|
|
|
$ git push -u origin {CURRENT_BRANCH}-explain-pricelists-xyz
|
|
|
|
#. Open a :abbr:`PR (Pull Request)` on GitHub to submit your changes for review.
|
|
|
|
#. Go to the `compare page of the odoo/documentation codebase
|
|
<https://github.com/odoo/documentation/compare>`_.
|
|
#. Select **{CURRENT_BRANCH}** for the base.
|
|
#. Click on :guilabel:`compare across forks`.
|
|
#. Select **<your_github_account>/odoo** for the head repository. Replace
|
|
`<your_github_account>` with the name of the GitHub account on which you created the
|
|
fork. Skip this step if you work at Odoo.
|
|
#. Review your changes and click on the :guilabel:`Create pull request` button.
|
|
#. Tick the :guilabel:`Allow edits from maintainer` checkbox. Skip this step if you work at
|
|
Odoo.
|
|
#. Complete the description and click on the :guilabel:`Create pull request` button again.
|
|
|
|
#. At the bottom of the page, check the mergeability status and address any issues.
|
|
#. As soon as your :abbr:`PR (Pull Request)` is ready for merging, a member of the Odoo team
|
|
is automatically assigned for review. If the reviewer has questions or remarks, they will
|
|
post them as comments and you will be notified by email. Those comments must be resolved
|
|
for the contribution to go forward.
|
|
#. Once your changes are approved, the reviewer merges them and they appear online the next
|
|
day.
|