[IMP] upgrade-util: link code documentation

Add direct code documentation from upgrade-util repo.
Adapt `extensions/github_link`.

Original commit: 3352d33

Part-of: #8836
Co-authored-by: Victor Feyens <[email protected]>

Author: aj-fuentes

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
 

conf.py

@@ -133,6 +133,24 @@
         )
         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 @@
 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'

extensions/github_link/__init__.py

@@ -24,6 +24,7 @@
 import os.path
 
 import werkzeug
+import contextlib
 
 
 def setup(app):
@@ -36,6 +37,7 @@ def linkcode_resolve(domain, info):
         # 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 linkcode_resolve(domain, info):
             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,37 +65,34 @@ def linkcode_resolve(domain, info):
             # 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 {
         'parallel_read_safe': True,
         'parallel_write_safe': True
     }
 
-def make_github_link(app, path, line=None, mode="blob", odoo_repository=False):
-    config = app.config
-
-    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,
-    )
+def make_github_link(app, project, path, line=None, mode="blob"):
+    branch = app.config.version or 'master'
+    if project == 'upgrade-util':
+        branch = 'master'
+
+    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)