khanh.pndc/odoo-docs
1
0
Fork 0
mirror of https://github.com/odoo/documentation.git synced 2025-12-12 07:29:27 +07:00
Code Issues Packages Projects Releases Wiki Activity

[IMP] contributing: documentation guidelines clarifications

Browse Source 
task-4367024

closes odoo/documentation#15128

X-original-commit: f666c3ed71
Signed-off-by: Audrey Vandromme (auva) <auva@odoo.com>
This commit is contained in:
Audrey (auva)
2025-10-31 14:50:02 +00:00
parent 9f9cb3d609
commit dc8cee7dfe
2 changed files with 163 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -8,6 +8,9 @@ RST guidelines and cheat sheet
We strongly recommend reading the :doc:`content_guidelines` and main :doc:`../documentation` We strongly recommend reading the :doc:`content_guidelines` and main :doc:`../documentation`
pages before contributing. pages before contributing.
General guidelines
==================
Follow the RST guidelines below when contributing to the documentation to help maintain consistency Follow the RST guidelines below when contributing to the documentation to help maintain consistency
with the rest of the documentation and facilitate the review process for the team: with the rest of the documentation and facilitate the review process for the team:
@@ -15,16 +18,10 @@ with the rest of the documentation and facilitate the review process for the tea
- :ref:`Be consistent with indentation. <contributing/rst/indentation>` - :ref:`Be consistent with indentation. <contributing/rst/indentation>`
- :ref:`Start a new line before the 100th character. <contributing/rst/character-limit>` - :ref:`Start a new line before the 100th character. <contributing/rst/character-limit>`
For hyperlinks:
- :ref:`Use relative links for internal URLs. <contributing/rst/relative-links>`
- :ref:`Do not break hyperlink targets when refactoring. <contributing/rst/update-targets>`
- :ref:`Do not use non-descriptive hyperlink labels. <contributing/rst/descriptive-labels>`
.. _contributing/rst/formatting: .. _contributing/rst/formatting:
Formatting Formatting
========== ----------
Use specific formatting to improve clarity and readability. For example, apply Use specific formatting to improve clarity and readability. For example, apply
:ref:`contributing/rst/menuselection` for menu paths, :ref:`contributing/rst/guilabel` :ref:`contributing/rst/menuselection` for menu paths, :ref:`contributing/rst/guilabel`
@@ -35,87 +32,10 @@ for notes, :ref:`contributing/rst/example` for examples, etc.
Add a blank line between different block elements, such as paragraphs, lists, and directives to Add a blank line between different block elements, such as paragraphs, lists, and directives to
ensure proper rendering and formatting. ensure proper rendering and formatting.
.. _contributing/rst/hyperlinks-guidelines:
Hyperlinks
==========
.. _contributing/rst/relative-links:
Internal URLs: relative links
-----------------------------
If you need to reference an :ref:`internal documentation page <contributing/rst/doc-hyperlinks>`
or a :ref:`file <contributing/rst/file>` that is not located in the same directory as the current
page, always use *relative file paths* instead of *absolute file paths*. This ensures that links
remain valid even with version updates, folder name changes, and directory structure
reorganizations.
An absolute file path indicates the target's location from the root directory. A relative file path
uses smart notations (such as `../` that redirects to the parent folder) to indicate the target's
location *relative* to that of the source document.
.. example::
.. note::
The purpose of the following example is to illustrate the difference between absolute and
relative links. Always use :ref:`contributing/rst/doc-hyperlinks` when referencing
documentation pages.
Given the following source file tree:
::
documentation
├── content
│ └── applications
│ │ └── sales
│ │ │ └── sales
│ │ │ │ └── products_prices
│ │ │ │ │ └── products
│ │ │ │ │ │ └── import.rst
│ │ │ │ │ │ └── variants.rst
│ │ │ │ │ └── prices.rst
A reference to :file:`prices.rst` and :file:`variants.rst` could be made from :file:`import.rst`
as follows:
#. Absolute:
- `documentation/content/applications/sales/sales/products_prices/prices.rst`
- `documentation/content/applications/sales/sales/products_prices/products/variants.rst`
#. Relative:
- `../prices.rst`
- `variants.rst`
.. _contributing/rst/update-targets:
Refactoring: hyperlink targets
------------------------------
When refactoring (improving without adding new content) section headings or hyperlink targets, take
care not to break any hyperlink reference to these targets or update them accordingly.
.. _contributing/rst/descriptive-labels:
Hyperlink labels
----------------
Do not use non-descriptive labels for :ref:`hyperlinks <contributing/rst/hyperlinks>`.
.. example::
| **Good example (descriptive label):**
| Please refer to the :doc:`Accounting documentation <../../../applications/finance/accounting>`.
| **Bad example (non-descriptive label):**
| Please refer to :doc:`this page <../../../applications/finance/accounting>`.
.. _contributing/rst/indentation: .. _contributing/rst/indentation:
Indentation Indentation
=========== -----------
Use only spaces (never tabs). Use only spaces (never tabs).
@@ -152,7 +72,7 @@ for bulleted lists, for example.
.. _contributing/rst/character-limit: .. _contributing/rst/character-limit:
100th-character limit 100th-character limit
===================== ---------------------
In RST, it is possible to break a line without forcing a line break on the rendered HTML. Make use In RST, it is possible to break a line without forcing a line break on the rendered HTML. Make use
of this feature to write **lines of maximum 100 characters**. It is not necessary to leave a of this feature to write **lines of maximum 100 characters**. It is not necessary to leave a
@@ -178,12 +98,7 @@ Headings
======== ========
For each formatting line (e.g., `===`), write as many symbols (`=`) as there are characters in the For each formatting line (e.g., `===`), write as many symbols (`=`) as there are characters in the
header. header. Use the symbols below to format headings:
The symbols used for the formatting are, in fact, not important. Only the order in which they are
written matters, as it determines the size of the decorated heading. This means that you may
encounter different heading formatting and in a different order, in which case you should follow the
formatting in place in the document. In any other case, use the formatting shown below.
+--------------+----------------------+ +--------------+----------------------+
| Heading size | Formatting | | Heading size | Formatting |
@@ -524,6 +439,18 @@ Nested lists
Hyperlinks Hyperlinks
========== ==========
.. note::
When using labels for hyperlinks, make sure they are clear and descriptive to indicate the
destination or purpose of the link.
.. example::
| **Good example (descriptive label):**
| Please refer to the :doc:`Accounting documentation <../../../applications/finance/accounting>`.
| **Bad example (non-descriptive label):**
| Please refer to :doc:`this page <../../../applications/finance/accounting>`.
.. _contributing/rst/external-hyperlinks: .. _contributing/rst/external-hyperlinks:
External hyperlinks External hyperlinks
@@ -532,10 +459,9 @@ External hyperlinks
External hyperlinks are links to a URL with a custom label. They follow the syntax: External hyperlinks are links to a URL with a custom label. They follow the syntax:
```label <URL>`_``. ```label <URL>`_``.
.. note:: .. important::
- Use :ref:`documentation page hyperlinks <contributing/rst/doc-hyperlinks>` when targeting Use :ref:`documentation page hyperlinks <contributing/rst/doc-hyperlinks>` when targeting
another documentation page. another documentation page.
- Do not use :ref:`non-descriptive hyperlink labels <contributing/rst/descriptive-labels>`.
.. list-table:: .. list-table::
:class: o-showcase-table :class: o-showcase-table
@@ -548,8 +474,8 @@ External hyperlinks are links to a URL with a custom label. They follow the synt
.. _contributing/rst/external-hyperlink-aliases: .. _contributing/rst/external-hyperlink-aliases:
External hyperlink aliases Aliases
-------------------------- ~~~~~~~
External hyperlink aliases allow creating shortcuts for external hyperlinks. The definition syntax External hyperlink aliases allow creating shortcuts for external hyperlinks. The definition syntax
is as follows: `.. _target: URL`. There are two ways to reference them, depending on the use case: is as follows: `.. _target: URL`. There are two ways to reference them, depending on the use case:
@@ -573,61 +499,69 @@ is as follows: `.. _target: URL`. There are two ways to reference them, dependin
A proof-of-concept_ is a simplified version, a prototype of what is expected to agree on A proof-of-concept_ is a simplified version, a prototype of what is expected to agree on
the main lines of expected changes. `PoC <proof-of-concept_>`_ is a common abbreviation. the main lines of expected changes. `PoC <proof-of-concept_>`_ is a common abbreviation.
.. _contributing/rst/custom-anchors: Internal documentation links
----------------------------
Custom anchors
--------------
Custom anchors follow the same syntax as external hyperlink aliases but without any URL. They allow
referencing a specific part of a RST file by using the target as an anchor. When users click the
reference, they are taken to the part of the documentation page where the target is defined.
The definition syntax is: `.. _target:`. There are two ways to reference them, both using the `ref`
markup:
#. ``:ref:`target``` creates a hyperlink to the anchor with the heading defined below as label.
#. ``:ref:`label <target>``` creates a hyperlink to the anchor with the given label.
.. important:: .. important::
As targets are visible from the entire documentation when referenced with the `ref` markup, When refactoring (improving without adding new content) section headings or hyperlink targets,
prefix the target name with the **app/section name** and the **file name**, separated by slashes, make sure not to break any hyperlink reference to these targets, or update them accordingly.
e.g., `accounting/taxes/configuration`.
.. note:: .. _contributing/rst/relative-links:
- Add custom anchors for all headings so they can be referenced from any documentation file or
within Odoo using documentation links.
- Notice that there is no `_` at the end, contrary to what is done with :ref:`external hyperlinks
<contributing/rst/external-hyperlinks>`.
.. list-table:: Relative links
:class: o-showcase-table ~~~~~~~~~~~~~~
* - Please refer to the :ref:`contributing/rst/hyperlinks-guidelines` section to learn more If you need to reference an :ref:`internal documentation page <contributing/rst/doc-hyperlinks>`
about :ref:`relative links <contributing/rst/relative-links>`. or a :ref:`file <contributing/rst/file>` that is not located in the same directory as the current
page, always use *relative file paths* instead of *absolute file paths*. This ensures that links
remain valid even with version updates, folder name changes, and directory structure
reorganizations.
* - .. code-block:: text An absolute file path indicates the target's location from the root directory. A relative file path
uses smart notations (such as `../` that redirects to the parent folder) to indicate the target's
location *relative* to that of the source document.
.. _contributing/rst/hyperlinks-guidelines: .. example::
Hyperlinks .. note::
========== The purpose of the following example is to illustrate the difference between absolute and
relative links. Always use :ref:`contributing/rst/doc-hyperlinks` when referencing
documentation pages.
.. _contributing/rst/relative-links: Given the following source file tree:
::
Use relative links for internal URLs documentation
------------------------------------ ├── content
│ └── applications
│ │ └── sales
│ │ │ └── sales
│ │ │ │ └── products_prices
│ │ │ │ │ └── products
│ │ │ │ │ │ └── import.rst
│ │ │ │ │ │ └── variants.rst
│ │ │ │ │ └── prices.rst
Please refer to the :ref:`contributing/rst/hyperlinks-guidelines` section to learn more A reference to :file:`prices.rst` and :file:`variants.rst` could be made from :file:`import.rst`
about :ref:`relative links <contributing/rst/relative-links>`. as follows:
#. Absolute:
- `documentation/content/applications/sales/sales/products_prices/prices.rst`
- `documentation/content/applications/sales/sales/products_prices/products/variants.rst`
#. Relative:
- `../prices.rst`
- `variants.rst`
.. _contributing/rst/doc-hyperlinks: .. _contributing/rst/doc-hyperlinks:
Documentation page hyperlinks Documentation page hyperlinks
----------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `doc` markup allows referencing a documentation page wherever it is in the file tree through a The `doc` markup allows referencing a documentation page wherever it is in the file tree through a
relative file path. There are two ways to use the markup, both using the `doc` markup: relative file path. There are two ways to use the `doc` markup:
#. ``:doc:`path_to_doc_page``` creates a hyperlink to the documentation page with the title of the #. ``:doc:`path_to_doc_page``` creates a hyperlink to the documentation page with the title of the
page as label. page as label.
@@ -649,10 +583,58 @@ relative file path. There are two ways to use the markup, both using the `doc` m
.. important:: .. important::
:ref:`Use relative links <contributing/rst/relative-links>` for documentation page hyperlinks. :ref:`Use relative links <contributing/rst/relative-links>` for documentation page hyperlinks.
.. _contributing/rst/custom-anchors:
Custom anchors
~~~~~~~~~~~~~~
Custom anchors follow the same syntax as :ref:`external hyperlink aliases
<contributing/rst/external-hyperlink-aliases>` but without any URL. They allow referencing a
specific part of a RST file by using the target as an anchor. When users click the reference, they
are taken to the part of the documentation page where the target is defined.
The definition syntax is: `.. _target:`. There are two ways to reference them, both using the `ref`
markup:
#. ``:ref:`target``` creates a hyperlink to the anchor with the heading defined below as the label.
#. ``:ref:`label <target>``` creates a hyperlink to the anchor with the given label.
.. important::
As targets are visible from the entire documentation when referenced with the `ref` markup,
prefix the target name with the **app/section name** and the **file name**, separated by slashes,
e.g., `accounting/taxes/configuration`.
.. note::
- Add custom anchors for all headings so they can be referenced from any documentation file or
within Odoo using documentation links.
- Notice that there is no `_` at the end, contrary to :ref:`external hyperlinks
<contributing/rst/external-hyperlinks>`.
.. list-table::
:class: o-showcase-table
* - Please refer to the :ref:`contributing/rst/external-hyperlinks` section to learn more
about :ref:`aliases <contributing/rst/external-hyperlink-aliases>`.
* - .. code-block:: text
.. _contributing/rst/external-hyperlinks:
External hyperlinks
-------------------
.. _contributing/rst/external-hyperlink-aliases:
Aliases
~~~~~~~
Please refer to the :ref:`contributing/rst/external-hyperlinks` section to learn more
about :ref:`aliases <contributing/rst/external-hyperlink-aliases>`.
.. _contributing/rst/download: .. _contributing/rst/download:
File download hyperlinks File download
------------------------ ~~~~~~~~~~~~~
The `download` markup allows referencing files (that are not necessarily :abbr:`RST The `download` markup allows referencing files (that are not necessarily :abbr:`RST
(reStructuredText)` documents) within the source tree to be downloaded. (reStructuredText)` documents) within the source tree to be downloaded.
@@ -1297,6 +1279,41 @@ Cards
List of technical guidelines to observe when writing with reStructuredText. List of technical guidelines to observe when writing with reStructuredText.
.. _contributing/rst/toctree:
Sub-pages
=========
The `toctree` directive is used to organize documentation into sections with sub-pages.
It adds a table of contents at the current location (i.e., the parent page), built from the files
listed in the directive. All RST files must be included in a TOC tree, unless the `orphan`
:ref:`metadata markup <contributing/rst/document-metadata>` is used.
.. tip::
- Use :ref:`relative links <contributing/rst/relative-links>` to list the files to be displayed
as sub-pages.
- Use the `titlesonly` parameter to only show the sub-pages' main headings when a parent page's
:ref:`content and TOC tree are displayed <contributing/rst/document-metadata>`.
.. example::
- TOC tree in the documentation's main TOC:
.. image:: rst_guidelines/website-toctree.png
:alt: Website section of the documentation
- `toctree` directive in `website.rst` (i.e., the parent page):
.. code-block:: text
.. toctree::
:titlesonly:
website/web_design
website/pages
website/configuration
website/reporting
website/mail_groups
.. _contributing/rst/document-metadata: .. _contributing/rst/document-metadata:
Document metadata Document metadata
@@ -1309,16 +1326,20 @@ metadata markups that specify a behavior for the entire page. They must be place
+-----------------+--------------------------------------------------------------------------------+ +-----------------+--------------------------------------------------------------------------------+
| **Metadata** | **Purpose** | | **Metadata** | **Purpose** |
+-----------------+--------------------------------------------------------------------------------+ +-----------------+--------------------------------------------------------------------------------+
| `show-content` | Make a toctree page accessible from the navigation menu. | | `show-content` | Make the content of a RST file that contains a |
| | :ref:`toc tree <contributing/rst/toctree>` visible and accessible from the |
| | documentation's main table of contents. |
+-----------------+--------------------------------------------------------------------------------+ +-----------------+--------------------------------------------------------------------------------+
| `show-toc` | Show the table of content on a page that has the `show-content` metadata | | `show-toc` | Display the page's :ref:`table of contents <contributing/rst/toctree>` |
| | markup. | | | when using the `show-content` metadata markup. Use the `titlesonly` parameter |
| | for the `toctree` directive to only show the sub-pages' main headings. |
+-----------------+--------------------------------------------------------------------------------+ +-----------------+--------------------------------------------------------------------------------+
| `hide-page-toc` | Hide the "On this page" sidebar and use full page width for the content. | | `hide-page-toc` | Hide the "On this page" sidebar and use full page width for the content. |
+-----------------+--------------------------------------------------------------------------------+ +-----------------+--------------------------------------------------------------------------------+
| `nosearch` | Exclude the document from search results. | | `nosearch` | Exclude the document from search results. |
+-----------------+--------------------------------------------------------------------------------+ +-----------------+--------------------------------------------------------------------------------+
| `orphan` | Suppress the need to include the document in a toctree. | | `orphan` | Suppress the need to include the document in a |
| | :ref:`TOC tree <contributing/rst/toctree>`. |
+-----------------+--------------------------------------------------------------------------------+ +-----------------+--------------------------------------------------------------------------------+
| `code-column` | | Show a dynamic side column that can be used to display interactive | | `code-column` | | Show a dynamic side column that can be used to display interactive |
| | tutorials or code excerpts. | | | tutorials or code excerpts. |

BIN
content/contributing/documentation/rst_guidelines/website-toctree.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.5 KiB