Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from

Conversation

aj-fuentes
Copy link
Contributor

@aj-fuentes aj-fuentes commented May 23, 2025

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
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

@robodoo
Copy link
Collaborator

robodoo commented May 23, 2025

Pull request status dashboard

@C3POdoo C3POdoo requested a review from a team May 23, 2025 13:40
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
@aj-fuentes aj-fuentes force-pushed the 16.0-improve_upg_utils_docs-afu branch from 18a1be3 to e33f02c Compare May 23, 2025 13:45
Copy link
Collaborator

@Feyensv Feyensv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

robodoo pushed a commit that referenced this pull request May 23, 2025
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]>
@robodoo robodoo closed this May 23, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants