[IMP] conf.py: strip module path from upgrade utils

The full module path in upgrade utils docs causes confusion for users.
See issues odoo/upgrade-util#272 and odoo/upgrade-util#175.

All utils we document online should be used via the top-level module
--i.e. `util.name` instead of `util.submodule.name`

Stripping the module path can be achieved in the configuration with
[`add_module_name=False`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-add_module_names)
Unfortunately this is a global setting that could affect other parts of
Odoo documentation. Thus in current patch we strip the module path from
the signature of `odoo.upgrade.util` functions and classes.

Technical links:
https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html#event-object-description-transform
https://www.sphinx-doc.org/en/master/extdev/nodes.html#sphinx.addnodes.desc_signature
https://github.com/sphinx-doc/sphinx/blob/v4.3.2/sphinx/domains/python.py#L512
https://sphinx-docutils.readthedocs.io/en/latest/docutils.nodes.html#docutils.nodes

closes #13519

Signed-off-by: Victor Feyens (vfe) <[email protected]>

Author: aj-fuentes

conf.py

@@ -380,6 +380,16 @@ def source_read_replace(app, docname, source):
         result = result.replace(f"{{{key}}}", app.config.source_read_replace_vals[key])
     source[0] = result
 
+def upgrade_util_signature_rewrite(app, domain, objtype, contentnode):
+    # Same as add_module_names=False but **only** for odoo.upgrade.util functions or classes
+    signature = contentnode.parent[0]
+    if objtype == 'function' and signature.astext().startswith('odoo.upgrade.util.'):
+        # <odoo.upgrade.util.modules>, <modules_installed>, <(cr, *modules)>
+        signature.pop(0)
+    if objtype == 'class' and signature.astext().startswith('class odoo.upgrade.util.'):
+        # <class >, <odoo.upgrade.util.pg.>, <PGRegexp>
+        signature.pop(1)
+
 def setup(app):
     # Generate all alternate URLs for each document
     app.add_config_value('project_root', None, 'env')
@@ -389,6 +399,7 @@ def setup(app):
     app.add_config_value('is_remote_build', None, 'env')  # Whether the build is remotely deployed
     app.add_config_value('source_read_replace_vals', {}, 'env')
     app.connect('source-read', source_read_replace)
+    app.connect('object-description-transform', upgrade_util_signature_rewrite)
 
     app.add_lexer('json', JsonLexer)
     app.add_lexer('xml', XmlLexer)