From aea601d6c37d42d4729fe740a2097fa7118bf477 Mon Sep 17 00:00:00 2001 From: "Audrey (auva)" Date: Fri, 31 Oct 2025 14:50:02 +0000 Subject: [PATCH] [IMP] contributing: documentation guidelines clarifications task-4367024 X-original-commit: f666c3ed7154017d4b43ab4f4cb1d777b7568214 --- .../documentation/rst_guidelines.rst | 299 ++++++++++-------- .../rst_guidelines/website-toctree.png | Bin 0 -> 3560 bytes 2 files changed, 160 insertions(+), 139 deletions(-) create mode 100644 content/contributing/documentation/rst_guidelines/website-toctree.png diff --git a/content/contributing/documentation/rst_guidelines.rst b/content/contributing/documentation/rst_guidelines.rst index 2c3d9830d9..76754f1b88 100644 --- a/content/contributing/documentation/rst_guidelines.rst +++ b/content/contributing/documentation/rst_guidelines.rst @@ -8,6 +8,9 @@ RST guidelines and cheat sheet We strongly recommend reading the :doc:`content_guidelines` and main :doc:`../documentation` pages before contributing. +General guidelines +================== + 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: @@ -15,16 +18,10 @@ with the rest of the documentation and facilitate the review process for the tea - :ref:`Be consistent with indentation. ` - :ref:`Start a new line before the 100th character. ` -For hyperlinks: - -- :ref:`Use relative links for internal URLs. ` -- :ref:`Do not break hyperlink targets when refactoring. ` -- :ref:`Do not use non-descriptive hyperlink labels. ` - .. _contributing/rst/formatting: Formatting -========== +---------- Use specific formatting to improve clarity and readability. For example, apply :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 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 ` -or a :ref:`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 `. - -.. 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: Indentation -=========== +----------- Use only spaces (never tabs). @@ -152,7 +72,7 @@ for bulleted lists, for example. .. _contributing/rst/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 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 -header. - -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. +header. Use the symbols below to format headings: +--------------+----------------------+ | Heading size | Formatting | @@ -524,6 +439,18 @@ Nested lists 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: External hyperlinks @@ -532,10 +459,9 @@ External hyperlinks External hyperlinks are links to a URL with a custom label. They follow the syntax: ```label `_``. -.. note:: - - Use :ref:`documentation page hyperlinks ` when targeting - another documentation page. - - Do not use :ref:`non-descriptive hyperlink labels `. +.. important:: + Use :ref:`documentation page hyperlinks ` when targeting + another documentation page. .. list-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: -External hyperlink aliases --------------------------- +Aliases +~~~~~~~ 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: @@ -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 the main lines of expected changes. `PoC `_ is a common abbreviation. -.. _contributing/rst/custom-anchors: +Internal documentation links +---------------------------- -Custom anchors --------------- +.. important:: + When refactoring (improving without adding new content) section headings or hyperlink targets, + make sure not to break any hyperlink reference to these targets, or update them accordingly. -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. +.. _contributing/rst/relative-links: -The definition syntax is: `.. _target:`. There are two ways to reference them, both using the `ref` -markup: +Relative links +~~~~~~~~~~~~~~ -#. ``:ref:`target``` creates a hyperlink to the anchor with the heading defined below as label. -#. ``:ref:`label ``` creates a hyperlink to the anchor with the given label. +If you need to reference an :ref:`internal documentation page ` +or a :ref:`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. -.. 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`. +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. -.. 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 what is done with :ref:`external hyperlinks - `. +.. example:: -.. list-table:: - :class: o-showcase-table + .. 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. - * - Please refer to the :ref:`contributing/rst/hyperlinks-guidelines` section to learn more - about :ref:`relative links `. + Given the following source file tree: + :: - * - .. code-block:: text + documentation + ├── content + │ └── applications + │ │ └── sales + │ │ │ └── sales + │ │ │ │ └── products_prices + │ │ │ │ │ └── products + │ │ │ │ │ │ └── import.rst + │ │ │ │ │ │ └── variants.rst + │ │ │ │ │ └── prices.rst - .. _contributing/rst/hyperlinks-guidelines: + A reference to :file:`prices.rst` and :file:`variants.rst` could be made from :file:`import.rst` + as follows: - Hyperlinks - ========== + #. Absolute: - .. _contributing/rst/relative-links: + - `documentation/content/applications/sales/sales/products_prices/prices.rst` + - `documentation/content/applications/sales/sales/products_prices/products/variants.rst` - Use relative links for internal URLs - ------------------------------------ + #. Relative: - Please refer to the :ref:`contributing/rst/hyperlinks-guidelines` section to learn more - about :ref:`relative links `. + - `../prices.rst` + - `variants.rst` .. _contributing/rst/doc-hyperlinks: Documentation page hyperlinks ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 page as label. @@ -649,10 +583,58 @@ relative file path. There are two ways to use the markup, both using the `doc` m .. important:: :ref:`Use relative links ` for documentation page hyperlinks. +.. _contributing/rst/custom-anchors: + +Custom anchors +~~~~~~~~~~~~~~ + +Custom anchors follow the same syntax as :ref:`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 ``` 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 + `. + +.. list-table:: + :class: o-showcase-table + + * - Please refer to the :ref:`contributing/rst/external-hyperlinks` section to learn more + about :ref:`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/download: -File download hyperlinks ------------------------- +File download +~~~~~~~~~~~~~ The `download` markup allows referencing files (that are not necessarily :abbr:`RST (reStructuredText)` documents) within the source tree to be downloaded. @@ -1297,6 +1279,41 @@ Cards 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 ` is used. + +.. tip:: + - Use :ref:`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 `. + +.. 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: Document metadata @@ -1309,16 +1326,20 @@ metadata markups that specify a behavior for the entire page. They must be place +-----------------+--------------------------------------------------------------------------------+ | **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 ` 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 | -| | markup. | +| `show-toc` | Display the page's :ref:`table of contents ` | +| | 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. | +-----------------+--------------------------------------------------------------------------------+ | `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 `. | +-----------------+--------------------------------------------------------------------------------+ | `code-column` | | Show a dynamic side column that can be used to display interactive | | | tutorials or code excerpts. | diff --git a/content/contributing/documentation/rst_guidelines/website-toctree.png b/content/contributing/documentation/rst_guidelines/website-toctree.png new file mode 100644 index 0000000000000000000000000000000000000000..007dc694ba696da1a7b671825f5b7a8ae2495062 GIT binary patch literal 3560 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 in}h)dgTY`-jsF3qJ>K`+YE2mc0000