NextERP/documentation
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[IMP] contributing/documentation: rewrite the contribution guide

Browse Source 
This commit restructures the contributing/documentation page to re-use
content introduced with the contributing/development page and to
display the two ways to contribute (github vs git) in content tabs
rather than sections.

The guide is simplified and updated to delegate long explanations to
other pages or websites, remove useless images and focus on getting
users ready to contribute.

task-2897123

Part-of: odoo/documentation#3265
This commit is contained in:
Antoine Vandevenne (anv) 2022-12-28 17:12:08 +00:00
parent f778ba89af
commit 872bee0033
13 changed files with 194 additions and 326 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
content/administration/install/install.rst
View File

@ -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

500
content/contributing/documentation.rst
View File

@ -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 <contributing/documentation/rst-intro>`
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
<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.
- **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
<documentation/rst_cheat_sheet>` 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
<https://en.wikipedia.org/wiki/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
<documentation/rst_cheat_sheet>`; 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 <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.
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
<https://github.com/join>`_ 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
<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:
#. .. include:: create_github_account.rst
#. .. include:: configure_github_account.rst
#. 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
#. .. 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 `<your_github_account>` 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 <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.
$ git remote add dev git@github.com:<your_github_account>/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 <https://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/<username>/documentation.git
$ cd documentation/
Replace `<username>` 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
<https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_.
.. code-block:: console
$ git clone git@github.com:<username>/documentation.git
$ cd documentation/
Replace `<username>` 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 <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/{BRANCH}/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:
.. group-tab:: Windows
.. code-block:: console
$ python3 --version
$ pip3 --version
$ git config --global core.autocrlf true
$ git config commit.template %CD%\commit_template.txt
#. Execute the following commands in a terminal to install the Python dependencies of the
documentation:
#. Install the latest release of `Python <https://wiki.python.org/moin/BeginnersGuide/Download>`_
and `pip <https://pip.pypa.io/en/stable/installation/>`_ on your machine.
#. Install the Python dependencies of the documentation with pip.
.. code-block:: console
$ cd documentation/
$ pip3 install -r requirements.txt
$ pip 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``
Verify that the installation directory of the Python dependencies is included in your system's
`PATH` variable.
.. _contributing/make:
.. tabs::
Make
~~~~
.. group-tab:: Linux and macOS
`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.
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`).
#. 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_>`_.
.. group-tab:: Windows
.. _contributing/pngquant:
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.
pngquant
~~~~~~~~
#. Install Make.
`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.
.. tabs::
#. 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 {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
<https://www.atlassian.com/git/tutorials/using-branches>`_ 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``.
Execute the following commands in a terminal to...
#. Navigate to the documentation folder:
.. group-tab:: Linux and macOS
.. code-block:: console
$ cd documentation/
$ sudo apt install make -y
#. Switch to the version {BRANCH}:
.. group-tab:: Windows
.. code-block:: console
Follow the `guide to install Make on Windows
<https://www.technewstoday.com/install-and-use-make-in-windows>`_.
$ git checkout {BRANCH}
#. `Install pngquant <https://pngquant.org/>`_.
#. That's it! You are ready to :ref:`make your first contribution
<contributing/documentation/first-contribution>` with Git.
#. Create your own branch which will be a copy of {BRANCH}:
.. _contributing/documentation/first-contribution:
.. code-block:: console
Make your first contribution
============================
$ git checkout -b {BRANCH}-my_contribution
.. tabs::
.. _contributing/perform-changes:
.. 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.
Perform your changes
--------------------
.. image:: documentation/fork-repository.png
:scale: 60%
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>`
#. 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.
#. .. include:: check_mergeability_status.rst
#. .. include:: handle_reviews.rst
#. .. include:: documentation/changes_approved.rst
.. tab:: Contribute with Git
.. important::
- If your changes include the addition of a new image, for instance :file:`my-image.png`, proceed
as follows:
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.
#. Make sure that the image is in ``.png`` format.
#. Execute the following commands in a terminal:
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/maintain/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
$ 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`.
- If your changes include renaming or moving an RST file to a new location, follow the `manual
for redirect rules <https://github.com/odoo/documentation/tree/{BRANCH}/redirects/MANUAL.md>`_
to create the appropriate redirect rule(s).
.. _contributing/preview-changes:
Preview your changes
--------------------
To preview your changes in a generated documentation, proceed as follows:
#. Execute the following commands in a terminal:
$ git switch -c {CURRENT_BRANCH}-explain-pricelists
.. code-block:: console
$ cd documentation/
$ make clean
$ make html
$ 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 you 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 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.
.. tip::
You can omit the :command:`make clean` command when no recent change has been made to the
hierarchy of documentation files.
Use :command:`make help` to learn about other useful commands.
#. 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:
#. Commit your changes. Write a clear commit message as instructed in the :doc:`Git guidelines
<development/git_guidelines>`.
.. code-block:: console
$ git add *
$ git add .
$ git commit
$ git push -u origin {BRANCH}-my_contribution
#. Go to `github.com/odoo/documentation/pulls
<https://github.com/odoo/documentation/pulls>`_ and click on the **New pull request** button.
#. Push your change to your fork, for which we added the remote alias `dev`.
.. image:: documentation/new-pull-request.png
.. example::
#. 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.
.. code-block:: console
.. image:: documentation/compare-across-forks.png
$ git push -u dev {CURRENT_BRANCH}-explain-pricelists
#. 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}**).
If you work at Odoo, push your changes directly to the main codebase whose remote alias is
`origin`.
.. image:: documentation/select-branches-fork.png
.. example::
#. 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.
.. code-block:: console
.. image:: documentation/create-pull-request.png
$ git push -u origin {CURRENT_BRANCH}-explain-pricelists-xyz
#. 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.
#. 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.
.. _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

1
content/contributing/documentation/changes_approved.rst Normal file
View File

@ -0,0 +1 @@
Once your changes are approved, the reviewer merges them and they appear online the next day!

BIN
content/contributing/documentation/commit-changes.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

BIN
content/contributing/documentation/compare-across-forks.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.6 KiB

3
content/contributing/documentation/content_guidelines.rst
View File

@ -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 <contributing/pngquant>`.
Don't forget to :ref:`compress your PNG files with pngquant
<contributing/documentation/first-contribution>`.
.. _contributing/screenshots:

BIN
content/contributing/documentation/create-pull-request.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.6 KiB

BIN
content/contributing/documentation/fork-button.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.1 KiB

BIN
content/contributing/documentation/new-pull-request.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.3 KiB

BIN
content/contributing/documentation/propose-changes.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.0 KiB

2
content/contributing/documentation/rst_guidelines.rst
View File

@ -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

BIN
content/contributing/documentation/select-branches-base.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 14 KiB

11
redirects/MANUAL.md
View File

@ -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 `<head/>`. 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 `<head/>`. 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`