[ADD] odoo-bin cloc cli subcommand.

Odoo cloc is a tool to count the number of relevant lines written in Python,
Javascript or XML. This can be used as rough metric for pricing maintenance of
customizations.

It has two modes of operation, either by providing a path:

    odoo-bin cloc -p module_path

Or by providing the name of a database:

    odoo-bin cloc --addons-path=dirs -d database

In the latter mode, only the custom code is accounted for.
Both modes can be used simultaneously.

Files that cannot be parsed are shown at the end of the report.
Parsing can fail due to syntax errors or excessive file size.

closes odoo/odoo#52635

X-original-commit: ae858c3ac66267b4726db459032b91a6be1cc1d6
Related: odoo/enterprise#11018
Signed-off-by: Olivier Dony (odo) <odo@openerp.com>
Co-authored-by: Thibault Francois <tfr@odoo.com>
Co-authored-by: Antoine Vandevenne (anv) <anv@odoo.com>

1 files changed, 156 insertions, 0 deletions

diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst
index 71b52bce8bb..9e90d9616d6 100644
--- a/doc/reference/cmdline.rst
+++ b/doc/reference/cmdline.rst
@@ -586,3 +586,159 @@ generation of the model's records to test your modules in databases containing n
 .. seealso::
 
     :ref:`reference/testing/populate`
+
+
+Cloc
+====
+
+.. program:: odoo-bin cloc
+
+Odoo Cloc is a tool to count the number of relevant lines written in
+Python, Javascript or XML. This can be used as a rough metric for pricing
+maintenance of extra modules.
+
+Command-line options
+--------------------
+.. option:: -d <database>, --database <database>
+
+| Process the code of all extra modules installed on the provided database,
+  and of all server actions and computed fields manually created in the provided
+  database.
+| The :option:`--addons-path` option is required to specify the path(s) to the
+  module folder(s).
+| If combined with :option:`--path`, the count will be that of the sum of both
+  options' results (with possible overlaps). At least one of these two options is
+  required to specify which code to process.
+
+.. code-block:: console
+
+   $ odoo-bin cloc --addons-path=addons -d my_database
+
+.. seealso::
+   - :ref:`reference/cmdline/cloc/database-option`
+
+
+.. option:: -p <path>, --path <path>
+
+| Process the files in the provided path.
+| If combined with :option:`--database`, the count will be that of the sum of both
+  options' results (with possible overlaps). At least one of these two options is
+  required to specify which code to process.
+
+.. code-block:: console
+
+   $ odoo-bin cloc -p addons/account
+
+
+Multiple paths can be provided by repeating the option.
+
+.. code-block:: console
+
+   $ odoo-bin cloc -p addons/account -p addons/sale
+
+.. seealso::
+   - :ref:`reference/cmdline/cloc/path-option`
+
+
+.. option:: --addons-path <directories>
+
+| Comma-separated list of directories in which modules are stored. These directories
+  are scanned for modules.
+| Required if the :option:`--database` option is used.
+
+
+.. option:: -c <directories>
+
+Specify a configuration file to use in place of the :option:`--addons-path` option.
+
+.. code-block:: console
+
+    $ odoo-bin cloc -c config.conf -d my_database
+
+
+.. option:: -v, --verbose
+
+Show the details of lines counted for each file.
+
+
+Processed files
+---------------
+
+.. _reference/cmdline/cloc/database-option:
+
+With the :option:`--database` option
+''''''''''''''''''''''''''''''''''''
+
+Odoo Cloc counts the lines in each file of extra installed modules in a
+given database. In addition, it counts the Python lines of server actions and
+custom computed fields that have been directly created in the database or
+imported.
+
+Some files are excluded from the count by default:
+
+- The manifest (:file:`__manifest__.py` or :file:`__openerp__.py`)
+- The contents of the folder :file:`static/lib`
+- The tests defined in the folder :file:`tests` and :file:`static/tests`
+- The XML files declared in the ``demo`` or ``demo_xml`` sections of the manifest
+
+For special cases, a list of files that should be ignored by Odoo Cloc can be defined
+per module. This is specified by the ``cloc_exclude`` entry of the manifest:
+
+.. code-block:: python
+
+    "cloc_exclude": [
+        "lib/common.py", # exclude a single file
+        "data/*.xml",    # exclude all XML files in a specific folder
+        "example/**/*",  # exclude all files in a folder hierarchy recursively
+    ]
+
+| The pattern ``**/*`` can be used to ignore an entire module. This can be useful
+  to exclude a module from maintenance service costs.
+| For more information about the pattern syntax, see `glob
+  <https://docs.python.org/3/library/pathlib.html#pathlib.Path.glob>`_.
+
+
+
+.. _reference/cmdline/cloc/path-option:
+
+With the :option:`--path` option
+''''''''''''''''''''''''''''''''
+
+This method works the same as with the :ref:`--database option
+<reference/cmdline/cloc/database-option>` if a manifest file is present in the given
+folder. Otherwise, it counts all files.
+
+
+Identifying Extra Modules
+-------------------------
+
+To distinguish between standard and extra modules, Odoo Cloc uses the following heuristic:
+modules that are located (real file system path, after following symbolic links)
+in the same parent directory as the ``base``, ``web`` or ``web_enterprise``
+standard modules are considered standard. Other modules are treated as extra modules.
+
+
+Error Handling
+--------------
+
+Some file cannot be counted by Odoo Cloc.
+Those file are reported at the end of the output.
+
+Max file size exceeded
+''''''''''''''''''''''
+
+Odoo Cloc rejects any file larger than 25MB. Usually, source files are smaller
+than 1 MB. If a file is rejected, it may be:
+
+- A generated XML file that contains lots of data. It should be excluded in the manifest.
+- A JavaScript library that should be placed in the :file:`static/lib` folder.
+
+Syntax Error
+''''''''''''
+
+Odoo Cloc cannot count the lines of code of a Python file with a syntax problem.
+If an extra module contains such files, they should be fixed to allow the module to
+load. If the module works despite the presence of those files, they are probably
+not loaded and should therefore be removed from the module, or at least excluded
+in the manifest via ``cloc_exclude``.
+