diff --git a/Makefile b/Makefile index e77eaa7fa..f3584baa7 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # Makefile for Sphinx documentation -# Pass WORKERS=auto for parallel build +# Pass WORKERS=1 for single-worker build ifndef WORKERS WORKERS = auto endif diff --git a/README.md b/README.md index 8b23f7fdc..e84d20131 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ ### Requirements -- [Git](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html#install-git) -- [Python 3.6, 3.7, or 3.8](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html#python) +- [Git](https://www.odoo.com/documentation/14.0/contributing/documentation.html#install-git) +- [Python 3.6, 3.7, or 3.8](https://www.odoo.com/documentation/14.0/contributing/documentation.html#python) - Python dependencies listed in the file [`requirements.txt`](https://github.com/odoo/documentation/tree/14.0/requirements.txt). -- [Make](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html#make) +- [Make](https://www.odoo.com/documentation/14.0/contributing/documentation.html#make) - A local copy of the [odoo/odoo repository in 14.0](https://github.com/odoo/odoo/tree/14.0) (Optional) ### Instructions @@ -23,7 +23,7 @@ 2. Open the file `documentation/_build/html/index.html` in your web browser to display the render. -3. See [this guide](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html#preview-your-changes) +3. See [this guide](https://www.odoo.com/documentation/14.0/contributing/documentation.html#preview-your-changes) for more detailed instructions. Optional: to fully build the developer documentation with inline docstrings for documented Python @@ -34,7 +34,7 @@ be shown. ## Contribute to the documentation For contributions to the content of the documentation, please refer to the -[Introduction Guide](https://www.odoo.com/documentation/14.0/contributing/documentation/introduction_guide.html). +[Introduction Guide](https://www.odoo.com/documentation/14.0/contributing/documentation.html). To **report a content issue**, **request new content** or **ask a question**, use the [repository's issue tracker](https://github.com/odoo/documentation-user/issues) as usual. diff --git a/content/contributing.rst b/content/contributing.rst index 8b8ecd456..b4989edfb 100644 --- a/content/contributing.rst +++ b/content/contributing.rst @@ -1,4 +1,3 @@ - ============ Contributing ============ diff --git a/content/contributing/documentation.rst b/content/contributing/documentation.rst index e98074551..9801a5222 100644 --- a/content/contributing/documentation.rst +++ b/content/contributing/documentation.rst @@ -1,12 +1,404 @@ +:show-content: -================================= -Contributing to the documentation -================================= +=================== +Write documentation +=================== .. toctree:: :titlesonly: - documentation/introduction_guide + documentation/content_guidelines documentation/rst_cheat_sheet documentation/rst_guidelines - documentation/content_guidelines \ No newline at end of file + +**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 +`_ 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:`content ` and + :doc:`RST ` 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 +`_ 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 + `_), 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 + ` and :doc:`RST ` guidelines. + +#. Click on the **Preview changes** button to review your contribution in a more human-readable + format. Be aware that the preview is not able to handle all markups correctly. Notes and tips, + for instance, are not correctly rendered. The version of your content published to the website + will be, however. + +#. Go to the bottom of the page to create a commit (:dfn:`what packs your changes together and + labels them with a commit message`) of your changes. + + #. | In first text box, describe your changes. For instance, "Fix a typo" and "Add documentation + for invoicing of sales orders" are two clear commit messages. + | In the second text box, justify *why* you made these changes, if you feel that it is not + obvious. + #. Select the option "Create a new branch for this commit and start a pull request." if you have + the choice (if you have partial or full edit writes on the repository). If not, skip this + step. + #. Click on the green button. It is either labelled "Commit changes" or "Propose file change". + + .. image:: 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 `_ 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 `_. 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 `_ 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 `_. +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 recommended release (`see README file + `_) 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 `_ 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/ + +#. 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 ` and :doc:`RST ` +guidelines. + +.. important:: + If your changes include the addition of a new image, for instance :file:`my_image.png`, proceed + as follows: + + #. Make sure that the image is in ``.png`` format. + #. Execute the following commands in a terminal: + + .. code-block:: console + + $ cd path-to-the-directory-of-the-image/ + $ pngquant my_image.png + + #. Delete :file:`my_image.png`. + #. Rename :file:`my_image-fs8.png` to :file:`my_image.png`. + +.. _contributing/preview-changes: + +Preview your changes +-------------------- + +To preview your changes in a generated documentation, proceed as follows: + +#. Execute the following commands in a terminal: + + .. code-block:: console + + $ cd documentation/ + $ make clean + $ make html + + .. tip:: + You can omit the :command:`make clean` command when no recent change has been made to the + hierarchy of documentation files. + +#. Fix any error or warning shown in the logs of the build. +#. Open the file :file:`documentation/_build/html/index.html` with your default web browser. + +.. note:: + These steps have for only purpose to show you the final results of your changes. They have no + impact on the documentation source files. + +.. _contributing/submit-changes: + +Submit your changes +------------------- + +.. important:: + We expect you to have basic knowledge of Git, which should be enough to cover the basic flow of a + one-time contribution. If you plan on submitting several contributions, work on older versions of + the documentation or perform any other advanced action, we recommend you to be confident with + Git. Help yourself with `this manual of Git `_ 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/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/ diff --git a/content/contributing/documentation/media/commit-changes.png b/content/contributing/documentation/commit-changes.png similarity index 100% rename from content/contributing/documentation/media/commit-changes.png rename to content/contributing/documentation/commit-changes.png diff --git a/content/contributing/documentation/media/compare-across-forks.png b/content/contributing/documentation/compare-across-forks.png similarity index 100% rename from content/contributing/documentation/media/compare-across-forks.png rename to content/contributing/documentation/compare-across-forks.png diff --git a/content/contributing/documentation/content_guidelines.rst b/content/contributing/documentation/content_guidelines.rst index 6e0a82623..db606ff91 100644 --- a/content/contributing/documentation/content_guidelines.rst +++ b/content/contributing/documentation/content_guidelines.rst @@ -1,4 +1,3 @@ - ================== Content guidelines ================== @@ -12,7 +11,7 @@ writing style, some rules still apply to give the reader more clarity and compre section of the documentation. Good knowledge of the ins and outs of **RST writing** is required to write and submit your contribution. Note that it also affects your writing style itself. - - :doc:`introduction_guide` + - :doc:`../documentation` - :doc:`rst_cheat_sheet` - :doc:`rst_guidelines` @@ -82,33 +81,33 @@ To write good titles and headings: - proper nouns (brands, product and service names, etc.) - app features, as written in the apps - .. important:: - Do not capitalize common nouns when they are not referred to as features. This is more likely - to happen in headings rather than in titles. +.. important:: + Do not capitalize common nouns when they are not referred to as features. This is more likely + to happen in headings rather than in titles. - +------------------+-----------------------------------+--------------------------------------------------------+ - | | Examples | Explanations | - +==================+===================================+========================================================+ - | | **Titles** | *Quotation Templates* | "Quotation Templates" is a feature in Odoo. | - | | (h1) +-----------------------------------+--------------------------------------------------------+ - | | *Lead Mining* | "Lead Mining" is a feature in Odoo. | - | +-----------------------------------+--------------------------------------------------------+ - | | *Resupply from another Warehouse* | "Warehouse" is capitalized as we refer to the feature | - | | | in the app rather than to a real warehouse. | - | +-----------------------------------+--------------------------------------------------------+ - | | *Synchronize Google Calendar | "Google Calendar" is a product and "Odoo" is a brand. | - | | with Odoo* | | - +------------------+-----------------------------------+--------------------------------------------------------+ - | | **Headings** | *Confirm the quotation* | "The quotation" is a common noun not referring to a | - | | (h2, h3, etc.) | | feature in Odoo. | - | +-----------------------------------+--------------------------------------------------------+ - | | *Test environment* | "Environment" is a common noun. | - | +-----------------------------------+--------------------------------------------------------+ - | | *Add a new Payment Acquirer* | "Payment Acquirers" is a feature in Odoo. | - | +-----------------------------------+--------------------------------------------------------+ - | | *Generate SEPA Direct Debit XML | "SEPA Direct Debit" and "XML" are considered as proper | - | | files to submit payments* | nouns. | - +------------------+-----------------------------------+--------------------------------------------------------+ ++------------------+-----------------------------------+--------------------------------------------------------+ +| | Examples | Explanations | ++==================+===================================+========================================================+ +| | **Titles** | *Quotation Templates* | "Quotation Templates" is a feature in Odoo. | +| | (h1) +-----------------------------------+--------------------------------------------------------+ +| | *Lead Mining* | "Lead Mining" is a feature in Odoo. | +| +-----------------------------------+--------------------------------------------------------+ +| | *Resupply from another Warehouse* | "Warehouse" is capitalized as we refer to the feature | +| | | in the app rather than to a real warehouse. | +| +-----------------------------------+--------------------------------------------------------+ +| | *Synchronize Google Calendar | "Google Calendar" is a product and "Odoo" is a brand. | +| | with Odoo* | | ++------------------+-----------------------------------+--------------------------------------------------------+ +| | **Headings** | *Confirm the quotation* | "The quotation" is a common noun not referring to a | +| | (h2, h3, etc.) | | feature in Odoo. | +| +-----------------------------------+--------------------------------------------------------+ +| | *Test environment* | "Environment" is a common noun. | +| +-----------------------------------+--------------------------------------------------------+ +| | *Add a new Payment Acquirer* | "Payment Acquirers" is a feature in Odoo. | +| +-----------------------------------+--------------------------------------------------------+ +| | *Generate SEPA Direct Debit XML | "SEPA Direct Debit" and "XML" are considered as proper | +| | files to submit payments* | nouns. | ++------------------+-----------------------------------+--------------------------------------------------------+ .. _contributing/document-structure: @@ -185,7 +184,7 @@ A few tips to improve your screenshots: #. If necessary, you can **edit** the screenshot to remove unnecessary fields and to narrow even more Odoo's display. -.. image:: media/screenshot-tips.gif +.. image:: content_guidelines/screenshot-tips.gif :align: center :alt: Three tips to take good screenshots for the Odoo documentation. diff --git a/content/contributing/documentation/media/screenshot-tips.gif b/content/contributing/documentation/content_guidelines/screenshot-tips.gif similarity index 100% rename from content/contributing/documentation/media/screenshot-tips.gif rename to content/contributing/documentation/content_guidelines/screenshot-tips.gif diff --git a/content/contributing/documentation/media/create-pull-request.png b/content/contributing/documentation/create-pull-request.png similarity index 100% rename from content/contributing/documentation/media/create-pull-request.png rename to content/contributing/documentation/create-pull-request.png diff --git a/content/contributing/documentation/media/edit-on-github.png b/content/contributing/documentation/edit-on-github.png similarity index 100% rename from content/contributing/documentation/media/edit-on-github.png rename to content/contributing/documentation/edit-on-github.png diff --git a/content/contributing/documentation/media/fork-button.png b/content/contributing/documentation/fork-button.png similarity index 100% rename from content/contributing/documentation/media/fork-button.png rename to content/contributing/documentation/fork-button.png diff --git a/content/contributing/documentation/media/fork-repository.png b/content/contributing/documentation/fork-repository.png similarity index 100% rename from content/contributing/documentation/media/fork-repository.png rename to content/contributing/documentation/fork-repository.png diff --git a/content/contributing/documentation/introduction_guide.rst b/content/contributing/documentation/introduction_guide.rst deleted file mode 100644 index 500e9e58d..000000000 --- a/content/contributing/documentation/introduction_guide.rst +++ /dev/null @@ -1,395 +0,0 @@ - -================== -Introduction guide -================== - -**First of all, thank you for landing here and helping us improve the user documentation of Odoo!** - -This introductory guide will help you acquire the tools and knowledge you need to write -documentation, whether you plan to make a minor content change or document an application from -scratch. - -.. _contributing/rst-intro: - -reStructuredText -================ - -Our documentation is written in **reStructuredText** (RST), a `lightweight markup language -`_ 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:`content ` and :doc:`RST - ` guidelines as you write documentation. This ensures that you stay consistent - with the rest of the documentation and facilitates the approval of your content changes as they - are reviewed by a redactor at Odoo. - -.. seealso:: - - :doc:`rst_cheat_sheet` - - :doc:`rst_guidelines` - - :doc:`content_guidelines` - -.. _contributing/getting-started: - -Getting started -=============== - -As our documentation is maintained on GitHub, you will need a free GitHub account. Click `here -`_ 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 - `_), 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 content writer at Odoo. - - .. image:: media/create-pull-request.png - -#. You're done! If your changes are approved straight away they will appear in the documentation the - very next day. It may also be the case that the reviewer has a question or a remark, so make sure - to check your notifications or your emails, depending on your account settings. - -.. _contributing/canonical-git-workflow: - -Use the canonical Git workflow -============================== - -.. _contributing/prepare-machine: - -Prepare your machine --------------------- - -.. _contributing/install-git: - -Install Git -~~~~~~~~~~~ - -We use `Git `_ 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 `_. 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 `_ and click on the - **Fork** button in the top right corner. - - .. image:: media/fork-button.png - -#. Execute the following commands in a terminal: - - .. code-block:: console - - $ git clone https://github.com/odoo/documentation - $ cd documentation/ - - .. important:: - If you do not have edit rights on the repository owned by Odoo, replace "odoo" with your - Github username in the URL of the command above. If you do have edit rights, it is not - necessary to fork the repository. - -#. In order to ease the collaboration between writers coming from many different systems and teams, - execute the following group of commands that correspond to your :abbr:`OS (Operating System)` in - a terminal. - - - Windows: - - .. code-block:: doscon - - $ cd documentation/ - $ git config --global core.autocrlf true - $ git config commit.template %CD%\commit_template.txt - - - Linux or Mac OS: - - .. code-block:: console - - $ cd documentation/ - $ git config --global core.autocrlf input - $ git config commit.template `pwd`/commit_template.txt - -.. _contributing/python: - -Python -~~~~~~ - -Because the documentation is written in :abbr:`RST (reStructuredText)`, it needs to be built -(:dfn:`converted to HTML`) in order to display nicely. This is done by the documentation generator -which takes the original :abbr:`RST (reStructuredText)` files as input, transforms the markups -in a human-readable format, and outputs HTML files to be read in your web browser. - -The documentation generator that we use is called `Sphinx `_. -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 recommended release (`see README file - `_) 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 `_ 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 14.0 in parallel -(conflicts of content would occur all the time), and in order to be able to create a :abbr:`PR -(Pull Request)`, you must `create a new branch -`_ starting from the branch 14.0. In other -words, you copy the entirety of this version’s files and give it another name. For this example, we -will go with ``14.0-my_contribution``. - -Execute the following commands in a terminal to... - -#. Navigate to the documentation folder: - - .. code-block:: console - - $ cd documentation/ - -#. Switch to the version 14.0: - - .. code-block:: console - - $ git checkout 14.0 - -#. Create your own branch which will be a copy of 14.0: - - .. code-block:: console - - $ git checkout -b 14.0-my_contribution - -.. _contributing/perform-changes: - -Perform your changes --------------------- - -You can now perform any change you want to the documentation files. These changes must be compliant -with :abbr:`RST (reStructuredText)` syntax (see :doc:`rst_cheat_sheet`) and with our -:doc:`guidelines `. - -.. 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 `_ and `this - interactive tutorial `_. - -#. Execute the following commands in a terminal: - - .. code-block:: console - - $ git add * - $ git commit - $ git push -u origin 14.0-my_contribution - -#. Go to `github.com/odoo/documentation/pulls - `_ and click on the **New pull request** button. - - .. image:: media/new-pull-request.png - -#. If you forked the base repository in the section :ref:`contributing/fetch-sources`, click on the - link **compare across forks** If not, skip this step. - - .. image:: media/compare-across-forks.png - -#. In the dropdown for the selection of the base branch (i.e., the version of the documentation that - your changes concern), make sure to select the version that your changes target (here **14.0**). - - .. image:: media/select-branches-fork.png - -#. Double-check your :abbr:`PR (Pull Request)` and, when ready, click again on the **Create pull - request** button to submit your changes for review by a redactor at Odoo. - - .. image:: media/create-pull-request.png - -#. You're done! If your changes are approved straight away they will appear in the documentation the - very next day. It may also be the case that the reviewer has a question or a remark, so make sure - to check your notifications or your emails, depending on your account settings. - - -.. _win-add-to-path: https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/ diff --git a/content/contributing/documentation/media/screenshot-max-width.png b/content/contributing/documentation/media/screenshot-max-width.png deleted file mode 100644 index 912aac521..000000000 Binary files a/content/contributing/documentation/media/screenshot-max-width.png and /dev/null differ diff --git a/content/contributing/documentation/media/new-pull-request.png b/content/contributing/documentation/new-pull-request.png similarity index 100% rename from content/contributing/documentation/media/new-pull-request.png rename to content/contributing/documentation/new-pull-request.png diff --git a/content/contributing/documentation/rst_cheat_sheet.rst b/content/contributing/documentation/rst_cheat_sheet.rst index e176038ce..e6a2902ca 100644 --- a/content/contributing/documentation/rst_cheat_sheet.rst +++ b/content/contributing/documentation/rst_cheat_sheet.rst @@ -1,4 +1,3 @@ - =============== RST cheat sheet =============== @@ -328,7 +327,7 @@ RST Render ****** -.. image:: media/create-invoice.png +.. image:: rst_cheat_sheet/create-invoice.png :align: center :alt: Create an invoice :height: 100 diff --git a/content/contributing/documentation/media/create-invoice.png b/content/contributing/documentation/rst_cheat_sheet/create-invoice.png similarity index 100% rename from content/contributing/documentation/media/create-invoice.png rename to content/contributing/documentation/rst_cheat_sheet/create-invoice.png diff --git a/content/contributing/documentation/rst_guidelines.rst b/content/contributing/documentation/rst_guidelines.rst index 830ff38a4..11980d770 100644 --- a/content/contributing/documentation/rst_guidelines.rst +++ b/content/contributing/documentation/rst_guidelines.rst @@ -1,4 +1,3 @@ - ============== RST guidelines ============== diff --git a/content/contributing/documentation/media/select-branches-base.png b/content/contributing/documentation/select-branches-base.png similarity index 100% rename from content/contributing/documentation/media/select-branches-base.png rename to content/contributing/documentation/select-branches-base.png diff --git a/content/contributing/documentation/media/select-branches-fork.png b/content/contributing/documentation/select-branches-fork.png similarity index 100% rename from content/contributing/documentation/media/select-branches-fork.png rename to content/contributing/documentation/select-branches-fork.png diff --git a/content/contributing/documentation/media/version-selector.png b/content/contributing/documentation/version-selector.png similarity index 100% rename from content/contributing/documentation/media/version-selector.png rename to content/contributing/documentation/version-selector.png diff --git a/extensions/odoo_theme/layout.html b/extensions/odoo_theme/layout.html index c0ccb1a51..b231697ad 100644 --- a/extensions/odoo_theme/layout.html +++ b/extensions/odoo_theme/layout.html @@ -64,7 +64,7 @@
{%- include "layout_templates/header.html" %} -