[REF] manifest

conf.py

@@ -191,6 +191,8 @@
 
     # Strange html domain logic used in memento pages
     'html_domain',
+
+    'badges',
 ]
 
 if odoo_dir_in_path:

content/developer/reference/backend/module.rst

@@ -27,131 +27,317 @@ dictionary, where each key specifies module metadatum.
         'description': """
         Description text
         """,
-        # data files always loaded at installation
         'data': [
-            'views/mymodule_view.xml',
+            'views/module_view.xml',
         ],
-        # data files containing optionally loaded demonstration data
         'demo': [
             'demo/demo_data.xml',
         ],
     }
 
-Available manifest fields are:
-
-``name`` (``str``, required)
-    the human-readable name of the module
-``version`` (``str``)
-    this module's version, should follow `semantic versioning`_ rules
-``description`` (``str``)
-    extended description for the module, in reStructuredText
-``author`` (``str``)
-    name of the module author
-``website`` (``str``)
-    website URL for the module author
-``license`` (``str``, defaults: ``LGPL-3``)
-    distribution license for the module.
-    Possible values:
-
-    * `GPL-2`
-    * `GPL-2 or any later version`
-    * `GPL-3`
-    * `GPL-3 or any later version`
-    * `AGPL-3`
-    * `LGPL-3`
-    * `Other OSI approved licence`
-    * `OEEL-1` (Odoo Enterprise Edition License v1.0)
-    * `OPL-1` (Odoo Proprietary License v1.0)
-    * `Other proprietary`
-
-``category`` (``str``, default: ``Uncategorized``)
-    classification category within Odoo, rough business domain for the module.
-
-    Although using `existing categories`_ is recommended, the field is
-    freeform and unknown categories are created on-the-fly. Category
-    hierarchies can be created using the separator ``/`` e.g. ``Foo / Bar``
-    will create a category ``Foo``, a category ``Bar`` as child category of
-    ``Foo``, and will set ``Bar`` as the module's category.
-``depends`` (``list(str)``)
-    Odoo modules which must be loaded before this one, either because this
-    module uses features they create or because it alters resources they
-    define.
-
-    When a module is installed, all of its dependencies are installed before
-    it. Likewise dependencies are loaded before a module is loaded.
-
-.. note::
-    Module `base` is always installed in any Odoo instance.
-    But you still need to specify it as dependency to make sure your module is updated when `base` is updated.
-
-``data`` (``list(str)``)
-    List of data files which must always be installed or updated with the
-    module. A list of paths from the module root directory
-``demo`` (``list(str)``)
-    List of data files which are only installed or updated in *demonstration
-    mode*
-``auto_install`` (``bool`` or ``list(str)``, default: ``False``)
-    If ``True``, this module will automatically be installed if all of its
-    dependencies are installed.
-
-    It is generally used for "link modules" implementing synergetic integration
-    between two otherwise independent modules.
-
-    For instance ``sale_crm`` depends on both ``sale`` and ``crm`` and is set
-    to ``auto_install``. When both ``sale`` and ``crm`` are installed, it
-    automatically adds CRM campaigns tracking to sale orders without either
-    ``sale`` or ``crm`` being aware of one another.
-
-    If it is a list, it must contain a subset of the dependencies. This module will automatically be
-    installed as soon as all the dependencies in the subset are installed. The remaining
-    dependencies will be automatically installed as well. If the list is empty, this module will
-    always be automatically installed regardless of its dependencies and these will be installed as
-    well.
-
-``external_dependencies`` (``dict(key=list(str))``)
-    A dictionary containing python and/or binary dependencies.
-
-    For python dependencies, the ``python`` key must be defined for this
-    dictionary and a list of python modules to be imported should be assigned
-    to it.
-
-    For binary dependencies, the ``bin`` key must be defined for this
-    dictionary and a list of binary executable names should be assigned to it.
-
-    The module won't be installed if either the python module is not installed
-    in the host machine or the binary executable is not found within the
-    host machine's PATH environment variable.
-``application`` (``bool``, default: ``False``)
-    Whether the module should be considered as a fully-fledged application
-    (``True``) or is just a technical module (``False``) that provides some
-    extra functionality to an existing application module.
-``assets`` (``dict``)
-    A definition of how all static files are loaded in various assets bundles.
-    See the :ref:`assets <reference/assets>` page for more details on how to
-    describe bundles.
-``installable`` (``bool`` default: ``True``)
-    Whether a user should be able to install the module from the Web UI or not.
-``maintainer`` (``str``)
-    Person or entity in charge of the maintenance of this module, by default
-    it is assumed that the author is the maintainer.
-``{pre_init, post_init, uninstall}_hook`` (``str``)
-    Hooks for module installation/uninstallation, their value should be a
-    string representing the name of a function defined inside the module's
-    ``__init__.py``.
-
-    ``pre_init_hook`` takes a cursor as its only argument, this function is
-    executed prior to the module's installation.
-
-    ``post_init_hook`` takes a cursor and a registry as its arguments, this
-    function is executed right after the module's installation.
-
-    ``uninstall_hook`` takes a cursor and a registry as its arguments, this
-    function is executed after the module's uninstallation.
-
-    These hooks should only be used when setup/cleanup required for this module
-    is either extremely difficult or impossible through the api.
-``active`` (``bool``)
-    Deprecated. Replaced by ``auto_install``.
-
-.. _semantic versioning: https://semver.org
+Available manifest keys:
+
+.. container:: d-flex justify-content-between pb-4
+
+    .. container::
+
+        * :ref:`application <application>`
+        * :ref:`assets <assets>`
+        * :ref:`author <author>`
+        * :ref:`auto_install <auto_install>`
+        * :ref:`category <category>`
+        * :ref:`data <data>`
+        * :ref:`demo <demo>`
+
+    .. container::
+
+        * :ref:`depends <depends>`
+        * :ref:`description <description>`
+        * :ref:`external_dependencies <external_dependencies>`
+        * :ref:`installable <installable>`
+        * :ref:`license <license>`
+        * :ref:`maintainer <maintainer>`
+        * :ref:`name <name>`
+
+    .. container::
+
+        * :ref:`post_init_hook <post_init_hook>`
+        * :ref:`pre_init_hook <pre_init_hook>`
+        * :ref:`uninstall_hook <uninstall_hook>`
+        * :ref:`version <version>`
+        * :ref:`website <website>`
+
+.. _application:
+
+**application**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`bool` :badge-secondary:`default: False`
+
+    Specifies if the module should be considered as a fully-fledged application (``True``) or is just a technical module (``False``) that provides some extra functionality to an existing application module.
+
+.. _assets:
+
+**assets**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`dict`
+
+    Specifies how all static files are loaded in various assets bundles.
+
+    See the :ref:`assets <reference/assets>` page for more details on how to describe bundles.
+
+.. _author:
+
+**author**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`dict`
+
+    Specifies the person or entity that authored the module.
+
+    If you are an employee at Odoo, it should be ``Odoo S.A.``.
+
+
+.. _auto_install:
+
+**auto_install**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`bool` :badge-primary:`list(str)`
+
+    If it is a ``bool``, it specifies if the module should be automatically installed once all of its dependencies are installed (``True``).
+
+    If it is a ``list(str)``, it must contain a subset of dependencies. It specifies if the module should be automatically installed once all the subset dependencies are installed and install the remaining dependencies.
+
+    ::
+
+        # Once the module 'crm' is installed, this module will be automatically installed as well as
+        # the modules 'sale', and 'web'.
+
+        {
+            'depends': ['crm', 'sale', 'web'],
+            'auto_install': ['crm'],
+        }
+
+
+    If the list of subset of dependencies is empty, the module will always be installed regardless of its dependencies and those will be installed as well.
+
+    ::
+
+        # This module will always be automatically installed as well as the modules 'crm', 'sale',
+        # and 'web'.
+
+        {
+            'depends': ['crm', 'sale', 'web'],
+            'auto_install': [],
+        }
+
+    This key is generally used for bridge modules implementing synergistic integration between two otherwise independent modules.
+
+    For example, ``sale_crm`` depends on both ``sale`` and ``crm`` and is set to ``auto_install``. When both ``sale`` and ``crm`` are installed, it will automatically add CRM campaigns tracking to sale orders without either ``sale`` or ``crm`` being aware of one another.
+
+.. _category:
+
+**category**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str` :badge-secondary:`default: Uncategorized`
+
+    Specifies the classification category (business domain) within Odoo.
+
+    Although using existing categories is recommended, the field is freeform and unknown categories are created on-the-fly. Category hierarchies can be created using the separator ``/`` e.g. ``Foo/Bar`` will create a category ``Foo``, a category ``Bar`` as a child category of ``Foo``, and will set ``Bar`` as the module’s category.
+
+.. _data:
+
+**data**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`list(str)`
+
+    Specifies the list of data files that are only installed or updated with the module.
+
+    The paths must be specified from the module root directory.
+
+.. _demo:
+
+**demo**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`list(str)`
+
+    Specifies the list of data files that are only installed or updated in *demonstration mode*.
+
+.. _depends:
+
+**depends**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`list(str)`
+
+    Specifies the list of modules that will be installed (or loaded) before installing (or loading) this module.
+
+    A module depends on another if it uses features from it or alter its resources.
+
+    The module base is always installed in any Odoo instance but it still needs to be specified as a dependency to make sure the module is updated when base is.
+
+.. _description:
+
+**description**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str`
+
+    Specifies the extended description of the module in *reStructuredText*.
+
+.. _external_dependencies:
+
+**external_dependencies**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`dict(key=list(str))`
+
+    Specifies a dictionary containing python and/or binary dependencies.
+
+    ::
+
+        {
+            'external_dependencies': {
+                'python': [...],
+                'bin': [...]
+            },
+        }
+
+    For python dependencies, the ``python`` key must be defined for this dictionary and a list of python modules to be imported should be assigned to it.
+
+    For binary dependencies, the ``bin`` key must be defined for this dictionary and a list of binary executable names should be assigned to it.
+
+    The module won’t be installed if either the python module is not installed in the host machine or the binary executable is not found within the host machine’s PATH environment variable.
+
+.. _installable:
+
+**installable**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`bool` :badge-secondary:`default: True`
+
+    Specifies if the user is able to install the module from the Web User Interface (``True``).
+
+.. _license:
+
+**license**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str` :badge-secondary:`default: LGPL-3`
+
+    Specifies the distribution license for the module.
+
+    Its value should be one of the following:
+
+    * ``GPL-2 or any later version``
+    * ``GPL-3 or any later version``
+    * ``AGPL-3``
+    * ``LGPL-3``
+    * ``Other OSI approved licence``
+    * ``OEEL-1`` (Odoo Enterprise Edition License v1.0)
+    * ``OPL-1`` (Odoo Proprietary License v1.0)
+    * ``Other proprietary``
+
+.. _maintainer:
+
+**maintainer**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str`
+
+    Specifies the person or entity in charge of the maintenance of this module.
+
+    By default, it is assumed that the author is also the maintainer.
+
+.. _name:
+
+**name**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str` :badge-danger:`required`
+
+    Specifies the human-readable name of the module.
+
+.. _post_init_hook:
+
+**post_init_hook**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str`
+
+    Specifies a function that will be executed right after the module’s installation.
+
+    Its value should be the name of a function defined inside the module’s ``__init__.py``.
+
+    This key should only be used when the setup required for this module is either extremely difficult or impossible through the api.
+
+.. _pre_init_hook:
+
+**pre_init_hook**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str`
+
+    Specifies a function that will be executed right before the module’s installation.
+
+    Its value should be the name of a function defined inside the module’s ``__init__.py``.
+
+    This key should only be used when the setup required for this module is either extremely difficult or impossible through the api.
+
+.. _uninstall_hook:
+
+**uninstall_hook**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str`
+
+    Specifies a function that will be executed right after the module’s uninstallation.
+
+    Its value should be the name of a function defined inside the module’s ``__init__.py``.
+
+    This key should only be used when the cleanup required for this module is either extremely difficult or impossible through the api.
+
+.. _version:
+
+**version**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str`
+
+    Specifies the `semantic version`_ of the module.
+
+.. _website:
+
+**website**
+
+.. container:: ps-3 pb-3
+
+    :badge-primary:`str`
+
+    Specifies the website url of the module author.
+
+.. _semantic version: https://semver.org
 .. _existing categories: {GITHUB_PATH}/odoo/addons/base/data/ir_module_category_data.xml

extensions/badges/__init__.py

@@ -0,0 +1,52 @@
+from docutils import nodes
+from sphinx.util.docutils import SphinxRole
+
+COLORS = {
+    'primary',
+    'secondary',
+    'success',
+    'danger',
+    'warning',
+    'info',
+    'light',
+    'dark',
+}
+
+
+def setup(app):
+    for color in COLORS:
+        app.add_role(f'badge-{color}', Badge(color))
+        app.add_role(f'badge-rounded-{color}', Badge(color, rounded=True))
+
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+
+def badge_classes(color, rounded=False):
+    classes = ['badge', f'bg-{color}']
+
+    if color in ('warning', 'info', 'light'):
+        classes.extend(['text-dark'])
+
+    if rounded:
+        classes.extend(['rounded-pill'])
+
+    return classes
+
+
+class Badge(SphinxRole):
+    def __init__(self, color, rounded=False):
+        super().__init__()
+        self.color = color
+        self.rounded = rounded
+
+    def run(self):
+        node = nodes.inline(
+            self.rawtext,
+            self.text,
+            classes=badge_classes(self.color, self.rounded)
+        )
+
+        return [node], []