diff --git a/README.md b/README.md index 5bead0dba..956011c88 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ - Python dependencies listed in the file `requirements.txt`. - Make - A local copy of the [odoo/odoo repository](https://github.com/odoo/odoo) (optional) +- A local copy of the [odoo/upgrade-util repository](https://github.com/odoo/upgrade-util) (optional) ### Instructions @@ -18,8 +19,9 @@ 3. See [this guide](https://www.odoo.com/documentation/latest/contributing/documentation.html) for more detailed instructions. -Optional: place your local copy of the `odoo/odoo` repository in the parent directory or in the root -directory of the documentation to build the latter with the documented Python docstrings. +Optional: place your local copy of the `odoo/odoo` and `odoo/upgrade-util` repositories in +the parent directory or in the root directory of the documentation to build the latter +with the documented Python docstrings. ## Contribute to the documentation diff --git a/conf.py b/conf.py index da376d041..de417e204 100644 --- a/conf.py +++ b/conf.py @@ -133,6 +133,24 @@ else: ) odoo_dir_in_path = True +if odoo_dir_in_path: + upgrade_util_dir = next(filter(Path.exists, [Path('upgrade-util'), Path('../upgrade-util')]), None) + if not upgrade_util_dir: + _logger.warning( + "Could not find Upgrade Utils sources directory in `upgrade_util`.\n" + "The developer documentation will be built but autodoc directives will be skipped.\n" + "In order to fully build the 'Developer' documentation, clone the repository with " + "`git clone https://github.com/odoo/upgrade-util` or create a symbolic link." + ) + odoo_dir_in_path = False + else: + _logger.info( + "Found Upgrade Util sources in %(directory)s", + {'directory': upgrade_util_dir.resolve()}, + ) + from odoo import upgrade + upgrade.__path__.append(str((upgrade_util_dir / 'src').resolve())) + # Mapping between odoo models related to master data and the declaration of the # data. This is used to point users to available xml_ids when giving values for # a field with the autodoc_field extension. @@ -250,6 +268,9 @@ redirects_dir = 'redirects/' sphinx_tabs_disable_tab_closing = True sphinx_tabs_disable_css_loading = True +# Autodoc ordering +autodoc_member_order = 'bysource' + #=== Options for HTML output ===# html_theme = 'odoo_theme' diff --git a/extensions/github_link/__init__.py b/extensions/github_link/__init__.py index b77c627bb..3993d538b 100644 --- a/extensions/github_link/__init__.py +++ b/extensions/github_link/__init__.py @@ -24,6 +24,7 @@ import inspect import os.path import werkzeug +import contextlib def setup(app): @@ -36,6 +37,7 @@ def setup(app): # TODO: js? if domain != 'py': return None + if not (app.config.github_user and app.config.github_project): return None @@ -53,10 +55,8 @@ def setup(app): return None # get original from decorated methods - try: - obj = getattr(obj, '_orig') - except AttributeError: - pass + with contextlib.suppress(AttributeError): + obj = obj._orig try: obj_source_path = inspect.getsourcefile(obj) @@ -65,14 +65,21 @@ def setup(app): # obj doesn't have a module, or something return None - import odoo # FIXME: make finding project root project-independent - project_root = os.path.join(os.path.dirname(odoo.__file__), '..') + if module.startswith('odoo.upgrade.util'): + from odoo.upgrade import util + project = 'upgrade-util' + project_root = os.path.join(os.path.dirname(util.__file__), '../..') + else: + import odoo + project = 'odoo' + project_root = os.path.join(os.path.dirname(odoo.__file__), '..') return make_github_link( app, - os.path.relpath(obj_source_path, project_root), - line, - odoo_repository=True) + project=project, + path=os.path.relpath(obj_source_path, project_root), + line=line, + ) app.config.linkcode_resolve = linkcode_resolve return { @@ -80,22 +87,12 @@ def setup(app): 'parallel_write_safe': True } -def make_github_link(app, path, line=None, mode="blob", odoo_repository=False): - config = app.config +def make_github_link(app, project, path, line=None, mode="blob"): + branch = app.config.version or 'master' + if project == 'upgrade-util': + branch = 'master' - user = config.github_user - project = config.github_project - if odoo_repository: - user = 'odoo' - project = 'odoo' - - urlpath = "/{user}/{project}/{mode}/{branch}/{path}".format( - user=user, - project=project, - branch=config.version or 'master', - path=path, - mode=mode, - ) + urlpath = f"/{app.config.github_user}/{project}/{mode}/{branch}/{path}" return werkzeug.urls.url_unparse(( 'https', 'github.com', @@ -116,4 +113,4 @@ def add_doc_link(app, pagename, templatename, context, doctree): source_suffix = app.config.source_suffix source_suffix = next(iter(source_suffix)) context['github_link'] = lambda mode='edit': make_github_link( - app, f'content/{pagename}{source_suffix}', mode=mode) + app, project=app.config.github_project, path=f'content/{pagename}{source_suffix}', mode=mode)