diff --git a/content/administration/install/install.rst b/content/administration/install/install.rst index ab2eeca2d..8dcbfe963 100644 --- a/content/administration/install/install.rst +++ b/content/administration/install/install.rst @@ -242,9 +242,8 @@ Source install The source "installation" is really about not installing Odoo, and running it directly from source instead. -This can be more convenient for module developers as the Odoo source is more easily accessible -than using packaged installation (for information or to build this documentation and have it -available offline). +It can be more convenient for module developers as the Odoo source is more easily accessible than +using packaged installation. It also makes starting and stopping Odoo more flexible and explicit than the services set up by the packaged installations, and allows overriding settings using diff --git a/content/contributing/documentation.rst b/content/contributing/documentation.rst index 8bf668825..502bbb13b 100644 --- a/content/contributing/documentation.rst +++ b/content/contributing/documentation.rst @@ -15,408 +15,276 @@ This introductory guide will help you acquire the tools and knowledge you need t documentation, whether you plan to make a minor content change or document an application from scratch. -.. _contributing/rst-intro: +.. seealso:: + :doc:`Discover other ways to contribute to Odoo <../contributing>` -reStructuredText -================ +Read the :ref:`introduction to the reStructuredText language ` +if you are not familiar with it. Then, you have two courses of action to start contributing to the +documentation, depending on whether you want to propose minor changes to existing content or you +instead want to work on significant changes to new and existing content. -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. +- **For minor changes**, for example, adding a paragraph or fixing a typo, we recommend **using the + GitHub interface**. This is the easiest and fastest way to submit your 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**, 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 to + first prepare your environment. -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. +.. _contributing/documentation/rst-intro: + +reStructuredText (RST) +====================== + +The documentation is written in **reStructuredText** (RST), a `lightweight markup language +`_ consisting of regular 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 minor changes to the content. + +If you need to learn about a specific markup, head over to our :doc:`cheat sheet for RST +`; it contains all the information you should ever need for the +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. + content changes as the Odoo team reviews them. .. seealso:: - :doc:`documentation/content_guidelines` - :doc:`documentation/rst_cheat_sheet` - :doc:`documentation/rst_guidelines` -.. _contributing/getting-started: +.. _contributing/documentation/setup: -Getting started -=============== +Environment setup +================= -As our documentation is maintained on GitHub, you will need a free GitHub account. Click `here -`_ to create one. +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. -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. - -#. Head over to the page that you want to change and click on the **Edit on GitHub** button in the - top right corner of the page. - -#. 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: +#. .. include:: create_github_account.rst +#. .. include:: configure_github_account.rst +#. Go to `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 +#. .. include:: configure_git_authorship.rst +#. Clone the sources with Git and navigate into the local repository. .. code-block:: console - $ git config --global user.name “Your Name” - $ git config --global user.email “youremail@example.com” + $ git clone git@github.com:odoo/documentation.git + $ cd documentation -.. _contributing/fetch-sources: +#. Configure Git to push changes to your fork rather than to the main codebase. In the commands + below, replace `` with the name of the GitHub account on which you created + the fork. Skip this step if you work at Odoo. -Fetch the sources -~~~~~~~~~~~~~~~~~ + .. code-block:: console -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. + $ git remote add dev git@github.com:/documentation.git -Prior to submitting a modification, you need to make a copy of the sources and download that copy on -your machine. Git's CLI (:dfn:`command-line interface`) allows downloading the sources by passing an -URL to its :command:`git clone` command. You must choose the protocol of the URL depending on what -you want to do with the sources: choose HTTPS if you intend to only build the documentation locally; -choose SSH if you plan on proposing content changes. - -#. Go to `github.com/odoo/documentation `_ and click on the - **Fork** button in the top right corner. If you work at Odoo, skip this step. - - .. image:: documentation/fork-button.png - -#. Execute the following commands in a terminal: +#. Configure Git to ease the collaboration between writers coming from different systems. .. tabs:: - .. tab:: Clone with HTTPS + .. group-tab:: Linux and macOS .. code-block:: console - $ git clone https://github.com//documentation.git - $ cd documentation/ + $ git config --global core.autocrlf input + $ git config commit.template `pwd`/commit_template.txt - Replace `` with your GitHub username. If you work at Odoo, replace it with - `odoo`. - - .. tab:: Clone with SSH - - .. important:: - Make sure that you `registered your SSH key on GitHub - `_. + .. group-tab:: Windows .. code-block:: console - $ git clone git@github.com:/documentation.git - $ cd documentation/ + $ git config --global core.autocrlf true + $ git config commit.template %CD%\commit_template.txt - Replace `` with your GitHub username. If you work at Odoo, replace it with - `odoo`. - -#. 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: +#. Install the latest release of `Python `_ + and `pip `_ on your machine. +#. Install the Python dependencies of the documentation with pip. .. code-block:: console - $ python3 --version - $ pip3 --version + $ pip install -r requirements.txt -#. Execute the following commands in a terminal to install the Python dependencies of the - documentation: + Verify that the installation directory of the Python dependencies is included in your system's + `PATH` variable. - .. code-block:: console + .. tabs:: - $ cd documentation/ - $ pip3 install -r requirements.txt + .. group-tab:: Linux and macOS -.. note:: - Depending on your :abbr:`OS (Operating System)`, you may need to run the commands ``python`` and - ``pip`` instead of ``python3`` and ``pip3`` + Follow the `guide to update the PATH variable on Linux and macOS + `_ with the installation path of the Python + dependencies (by default :file:`~/.local/bin`). -.. _contributing/make: + .. group-tab:: Windows -Make -~~~~ + Follow the `guide to update the PATH variable on Windows + `_ + with the installation path of the Python dependencies. -`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. +#. Install Make. -#. Download and install **Make** on your machine. -#. Verify that `the installation folder of Make is included in your system's PATH variable - `_. + .. tabs:: -.. _contributing/pngquant: + .. group-tab:: Linux and macOS -pngquant -~~~~~~~~ + .. code-block:: console -`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. + $ sudo apt install make -y -#. Download and install **pngquant** on your machine. -#. Verify that `the installation folder of pngquant is included in your system's PATH variable - `_. + .. group-tab:: Windows -.. _contributing/prepare-version: + Follow the `guide to install Make on Windows + `_. -Prepare your version --------------------- +#. `Install pngquant `_. +#. That's it! You are ready to :ref:`make your first contribution + ` with Git. -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 {BRANCH} 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 {BRANCH}. In -other words, you copy the entirety of this version’s files and give it another name. For this -example, we will go with ``{BRANCH}-my_contribution``. +.. _contributing/documentation/first-contribution: -Execute the following commands in a terminal to... +Make your first contribution +============================ -#. Navigate to the documentation folder: +.. tabs:: - .. code-block:: console + .. tab:: Contribute from the GitHub interface + #. .. include:: create_github_account.rst + #. 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. - $ cd documentation/ + .. image:: documentation/fork-repository.png + :scale: 60% -#. Switch to the version {BRANCH}: + #. Make the desired changes while taking care of following the :doc:`content + ` and :doc:`RST ` + guidelines. - .. code-block:: console + .. 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. - $ git checkout {BRANCH} + #. 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. -#. Create your own branch which will be a copy of {BRANCH}: + .. image:: documentation/propose-changes.png + :scale: 60% - .. code-block:: console + #. 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. + #. .. include:: check_mergeability_status.rst + #. .. include:: handle_reviews.rst + #. .. include:: documentation/changes_approved.rst - $ git checkout -b {BRANCH}-my_contribution + .. tab:: Contribute with Git -.. _contributing/perform-changes: + .. important:: + Some steps of this guide require to be comfortable with Git. Here are some `tutorials + `_ and an `interactive training + `_ if you are stuck at some point. -Perform your changes --------------------- + 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. -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. + #. 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 + ` 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`. -.. important:: - - If your changes include the addition of a new image, for instance :file:`my-image.png`, proceed - as follows: + .. example:: - #. Make sure that the image is in ``.png`` format. - #. Execute the following commands in a terminal: + .. code-block:: console - .. code-block:: console + $ git switch -c {CURRENT_BRANCH}-explain-pricelists - $ cd path/to/the/directory/of/the/image/ - $ pngquant my-image.png + .. code-block:: console - #. Delete :file:`my-image.png`. - #. Rename :file:`my-image-fs8.png` to :file:`my-image.png`. - - If your changes include renaming or moving an RST file to a new location, follow the `manual - for redirect rules `_ - to create the appropriate redirect rule(s). + $ git switch -c {CURRENT_BRANCH}-explain-pricelists-xyz -.. _contributing/preview-changes: + #. Make the desired changes while taking care of following the :doc:`content + ` and :doc:`RST ` + guidelines. + #. Compress all PNG images that you added or modified. -Preview your changes --------------------- + .. code-block:: console -To preview your changes in a generated documentation, proceed as follows: + $ pngquant path/to/image.png + $ mv path/to/image-fs8.png path/to/image.png -#. Execute the following commands in a terminal: + #. Write a `redirect rule + `_ for every RST + file that your renamed. + #. Build the documentation with :command:`make`. Then, open :file:`_build/index.html` in your + web browser to browse the documentation with your changes. - .. code-block:: console + .. tip:: + Use :command:`make help` to learn about other useful commands. - $ cd documentation/ - $ make clean - $ make html + #. Commit your changes. Write a clear commit message as instructed in the :doc:`Git guidelines + `. - .. tip:: - You can omit the :command:`make clean` command when no recent change has been made to the - hierarchy of documentation files. + .. code-block:: console -#. 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. + $ git add . + $ git commit -.. 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. + #. Push your change to your fork, for which we added the remote alias `dev`. -.. _contributing/submit-changes: + .. example:: -Submit your changes -------------------- + .. code-block:: console -.. 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 `_. + $ git push -u dev {CURRENT_BRANCH}-explain-pricelists -#. Execute the following commands in a terminal: + If you work at Odoo, push your changes directly to the main codebase whose remote alias is + `origin`. - .. code-block:: console + .. example:: - $ git add * - $ git commit - $ git push -u origin {BRANCH}-my_contribution + .. code-block:: console -#. Go to `github.com/odoo/documentation/pulls - `_ and click on the **New pull request** button. + $ git push -u origin {CURRENT_BRANCH}-explain-pricelists-xyz - .. image:: documentation/new-pull-request.png + #. Open a :abbr:`PR (Pull Request)` on GitHub to submit your changes for review. -#. 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. + #. Go to the `compare page of the odoo/documentation codebase + `_. + #. Select **{CURRENT_BRANCH}** for the base. + #. Click on :guilabel:`compare across forks`. + #. Select **/odoo** for the head repository. Replace + `` 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. - .. 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 - **{BRANCH}**). - - .. 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/ + #. .. include:: check_mergeability_status.rst + #. .. include:: handle_reviews.rst + #. .. include:: documentation/changes_approved.rst diff --git a/content/contributing/documentation/changes_approved.rst b/content/contributing/documentation/changes_approved.rst new file mode 100644 index 000000000..6e060a302 --- /dev/null +++ b/content/contributing/documentation/changes_approved.rst @@ -0,0 +1 @@ +Once your changes are approved, the reviewer merges them and they appear online the next day! diff --git a/content/contributing/documentation/commit-changes.png b/content/contributing/documentation/commit-changes.png deleted file mode 100644 index f020ac025..000000000 Binary files a/content/contributing/documentation/commit-changes.png and /dev/null differ diff --git a/content/contributing/documentation/compare-across-forks.png b/content/contributing/documentation/compare-across-forks.png deleted file mode 100644 index 36dd14806..000000000 Binary files a/content/contributing/documentation/compare-across-forks.png and /dev/null differ diff --git a/content/contributing/documentation/content_guidelines.rst b/content/contributing/documentation/content_guidelines.rst index cc7bdd263..043c20a3c 100644 --- a/content/contributing/documentation/content_guidelines.rst +++ b/content/contributing/documentation/content_guidelines.rst @@ -182,7 +182,8 @@ content. However, avoid adding too many images: it isn't necessary to illustrate features, and it may overload your page. .. important:: - Don't forget to :ref:`compress your PNG files with pngquant `. + Don't forget to :ref:`compress your PNG files with pngquant + `. .. _contributing/screenshots: diff --git a/content/contributing/documentation/create-pull-request.png b/content/contributing/documentation/create-pull-request.png deleted file mode 100644 index fa559c7e0..000000000 Binary files a/content/contributing/documentation/create-pull-request.png and /dev/null differ diff --git a/content/contributing/documentation/fork-button.png b/content/contributing/documentation/fork-button.png deleted file mode 100644 index 9b7179288..000000000 Binary files a/content/contributing/documentation/fork-button.png and /dev/null differ diff --git a/content/contributing/documentation/new-pull-request.png b/content/contributing/documentation/new-pull-request.png deleted file mode 100644 index 158055cef..000000000 Binary files a/content/contributing/documentation/new-pull-request.png and /dev/null differ diff --git a/content/contributing/documentation/propose-changes.png b/content/contributing/documentation/propose-changes.png new file mode 100644 index 000000000..8358afd4b Binary files /dev/null and b/content/contributing/documentation/propose-changes.png differ diff --git a/content/contributing/documentation/rst_guidelines.rst b/content/contributing/documentation/rst_guidelines.rst index d8d23cacd..08de01f55 100644 --- a/content/contributing/documentation/rst_guidelines.rst +++ b/content/contributing/documentation/rst_guidelines.rst @@ -10,7 +10,7 @@ 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 +relative file path makes use of smart notations (such as ``../`` that redirects to the parent folder) to indicate the location of the target *relative* to that of the source document. Example diff --git a/content/contributing/documentation/select-branches-base.png b/content/contributing/documentation/select-branches-base.png deleted file mode 100644 index efd6ac1c1..000000000 Binary files a/content/contributing/documentation/select-branches-base.png and /dev/null differ diff --git a/redirects/MANUAL.md b/redirects/MANUAL.md index c8580bd7b..fc1174a13 100644 --- a/redirects/MANUAL.md +++ b/redirects/MANUAL.md @@ -9,8 +9,8 @@ rule that applies to a single documentation page. ## How do redirect rules work? -For each redirect rule, the redirects Sphinx extension creates a blank HTML file at the location of -the specified target with only the `meta http-equiv="refresh"` tag in the ``. When users +For each redirect rule, the **redirects** Sphinx extension creates a blank HTML file at the location +of the specified target with only the `meta http-equiv="refresh"` tag in the ``. When users visit that HTML file, a client-side redirection is triggered and the browser loads the target documentation page. @@ -25,10 +25,9 @@ information. it. 2. Look for the block of redirect rules related to the one you want to add. For example, search for a block of redirect rules that start with `applications/sales/sales` if you are adding a redirect - rule for a page in the Sales app. If the block does not exist yet, create it. Ideally, there - should be one block per app or scope and redirect rules should be sorted alphabetically. -3. Add a new line for your redirect rule at the end of the block. The line should follow this - pattern: + rule for a page in the Sales app. If the block does not exist yet, create it. There should be one + block per app or scope and redirect rules must be sorted alphabetically. +3. Insert your redirect rule in the block. The line should follow this pattern: `path/to/old/file.rst path/to/new/file.rst # optional comment`