From bd5cd8019c2f5304360a7d478aebe28f7ef688ee Mon Sep 17 00:00:00 2001 From: Alvaro Fuentes Date: Fri, 23 May 2025 12:58:33 +0000 Subject: [PATCH] [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 X-original-commit: fa506a68dbb89ede159ae0bcfb18827a7a6d45b9 --- conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/conf.py b/conf.py index 21b0855888..509a5d20c4 100644 --- a/conf.py +++ b/conf.py @@ -386,6 +386,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.'): + # , , <(cr, *modules)> + signature.pop(0) + if objtype == 'class' and signature.astext().startswith('class odoo.upgrade.util.'): + # , , + signature.pop(1) + def setup(app): # Generate all alternate URLs for each document app.add_config_value('project_root', None, 'env') @@ -395,6 +405,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) # TODO uncomment after moving to >= v7.2.5 to also substitute placeholders in included files. # See https://github.com/sphinx-doc/sphinx/commit/ff1831 # app.connect('include-read', source_read_replace)