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

[IMP] contributing: list supported metadata directives

Browse Source 
The opportunity is also take to refresh the section about admonitions
and to add undocumented admonitions.

task-2534984
This commit is contained in:
Antoine Vandevenne (anv) 2021-06-08 15:29:33 +02:00 committed by Antoine Vandevenne (anv)
parent 1faf5486a7
commit ec1dc7b632
1 changed files with 108 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
content/contributing/documentation/rst_cheat_sheet.rst
View File

@ -14,28 +14,31 @@ Headings
encounter different heading formatting and in a different order, in which case you should follow 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. the formatting in place in the document. In any other case, use the formatting shown below.
+--------------+---------------+-------------------------------+ +--------------+---------------+
| Heading size | Formatting | Min/Max number of occurrences | | Heading size | Formatting |
+==============+===============+===============================+ +==============+===============+
| H1 | | ``=======`` | 1/1 | | H1 | | ``=======`` |
| | | ``Heading`` | | | | | ``Heading`` |
| | | ``=======`` | | | | | ``=======`` |
+--------------+---------------+-------------------------------+ +--------------+---------------+
| H2 | | ``Heading`` | 0/∞ | | H2 | | ``Heading`` |
| | | ``=======`` | | | | | ``=======`` |
+--------------+---------------+-------------------------------+ +--------------+---------------+
| H3 | | ``Heading`` | 0/∞ | | H3 | | ``Heading`` |
| | | ``-------`` | | | | | ``-------`` |
+--------------+---------------+-------------------------------+ +--------------+---------------+
| H4 | | ``Heading`` | 0/∞ | | H4 | | ``Heading`` |
| | | ``~~~~~~~`` | | | | | ``~~~~~~~`` |
+--------------+---------------+-------------------------------+ +--------------+---------------+
| H5 | | ``Heading`` | 0/∞ | | H5 | | ``Heading`` |
| | | ``*******`` | | | | | ``*******`` |
+--------------+---------------+-------------------------------+ +--------------+---------------+
| H6 | | ``Heading`` | 0/∞ | | H6 | | ``Heading`` |
| | | ``^^^^^^^`` | | | | | ``^^^^^^^`` |
+--------------+---------------+-------------------------------+ +--------------+---------------+
.. important::
Each document must have **exactly one H1 heading**. No less, no more.
.. _contributing/markup: .. _contributing/markup:
@ -373,13 +376,13 @@ RST
.. code-block:: rst .. code-block:: rst
.. note:: .. note::
Use this to get the attention of the reader about additional information. Use this admonition to grab the reader's attention about additional information.
Render Render
~~~~~~ ~~~~~~
.. note:: .. note::
Use this to get the attention of the reader about additional information. Use this admonition to grab the reader's attention about additional information.
.. _contributing/tip: .. _contributing/tip:
@ -392,15 +395,32 @@ RST
.. code-block:: rst .. code-block:: rst
.. tip:: .. tip::
Use this to inform the reader about a useful trick that requires an Use this admonition to inform the reader about a useful trick that requires an action.
action.
Render Render
~~~~~~ ~~~~~~
.. tip:: .. tip::
Use this to inform the reader about a useful trick that requires an Use this admonition to inform the reader about a useful trick that requires an action.
action.
.. _contributing/exercise:
Exercise
--------
RST
~~~
.. code-block:: rst
.. exercise::
Use this admonition to suggest an exercise to the reader.
Render
~~~~~~
.. exercise::
Use this admonition to suggest an exercise to the reader.
.. _contributing/important: .. _contributing/important:
@ -413,13 +433,13 @@ RST
.. code-block:: rst .. code-block:: rst
.. important:: .. important::
Use this to notify the reader about an important information. Use this admonition to notify the reader about an important information.
Render Render
~~~~~~ ~~~~~~
.. important:: .. important::
Use this to notify the reader about an important information. Use this admonition to notify the reader about an important information.
.. _contributing/warning: .. _contributing/warning:
@ -432,15 +452,15 @@ RST
.. code-block:: rst .. code-block:: rst
.. warning:: .. warning::
Use this to require the reader to proceed with caution with what is Use this admonition to require the reader to proceed with caution with what is described in
described in the warning. the warning.
Render Render
~~~~~~ ~~~~~~
.. warning:: .. warning::
Use this to require the reader to proceed with caution with what is Use this admonition to require the reader to proceed with caution with what is described in the
described in the warning. warning.
.. _contributing/danger: .. _contributing/danger:
@ -453,13 +473,65 @@ RST
.. code-block:: rst .. code-block:: rst
.. danger:: .. danger::
Use this to alarm the reader about a serious threat. Use this admonition to bring the reader's attention to a serious threat.
Render Render
~~~~~~ ~~~~~~
.. danger:: .. danger::
Use this to alarm the reader about a serious threat. Use this admonition to bring the reader's attention to a serious threat.
.. _contributing/custom-admonition:
Custom
------
RST
~~~
.. code-block:: rst
.. admonition:: Title
Customize this admonition with a **Title** of your choice.
Render
~~~~~~
.. admonition:: Title
Customize this admonition with a **Title** of your choice.
.. _contributing/document-metadata:
Document metadata
=================
| Sphinx supports document-wide metadata directives that specify a behavior for the entire page.
| They must be placed between colons (`:`) at the top of the source file.
+-----------------+--------------------------------------------------------------------------------+
| **Metadata** | **Purpose** |
+-----------------+--------------------------------------------------------------------------------+
| `show-content` | Make a toctree page accessible from the navigation menu. |
+-----------------+--------------------------------------------------------------------------------+
| `code-column` | | Show a dynamic side column that can be used to display interactive |
| | tutorials or code excerpts. |
| | | For example, see :doc:`/developer/webservices/upgrade` or |
| | :doc:`/applications/finance/accounting/overview/main_concepts/memento`. |
+-----------------+--------------------------------------------------------------------------------+
| `hide-page-toc` | Hide the "On this page" sidebar and use full page width for the content. |
+-----------------+--------------------------------------------------------------------------------+
| `custom-css` | Link CSS files (comma-separated) to the document. |
+-----------------+--------------------------------------------------------------------------------+
| `custom-js` | Link JS files (comma-separated) to the document. |
+-----------------+--------------------------------------------------------------------------------+
| `classes` | Assign the specified classes to the `<main/>` element of the document. |
+-----------------+--------------------------------------------------------------------------------+
| `orphan` | Suppress the need to include the document in a toctree. |
+-----------------+--------------------------------------------------------------------------------+
| `nosearch` | Exclude the document from search results. |
+-----------------+--------------------------------------------------------------------------------+
.. _contributing/formatting-tips: .. _contributing/formatting-tips: