Fix sphinx warnings and show inheritance in API docs (#1580)

Signed-off-by: Jean-Christophe Morin <[email protected]>

docs/source/conf.py

@@ -6,6 +6,10 @@
 import os
 import sys
 
+import sphinx.domains
+import sphinx.addnodes
+import sphinx.application
+
 # Add path to rez's source.
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', 'src')))
 
@@ -39,6 +43,17 @@
 
 templates_path = ['_templates']
 
+nitpick_ignore = [
+    # TODO: Remove once we unvendor enum.
+    ("py:class", "rez.solver._Common"),
+    ("py:class", "_thread._local"),
+    ("py:class", "rez.utils.platform_._UnixPlatform")
+]
+
+nitpick_ignore_regex = [
+    ("py:class", r"rez\.vendor\..*"),
+]
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
@@ -70,6 +85,12 @@
 # autoclass_content = 'both'
 autodoc_class_signature = 'separated'
 autodoc_member_order = 'bysource'
+autodoc_inherit_docstrings = True
+autodoc_default_options = {
+    "show-inheritance": True,
+    "undoc-members": True,
+    "inherited-members": True,
+}
 
 
 # -- Options for extlinks extension -----------------------------------------
@@ -82,4 +103,40 @@
 # -- Options for todo extension ---------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
 
-todo_emit_warnings = True
+todo_emit_warnings = False
+
+
+# -- Custom -----------------------------------------------------------------
+
+def handle_ref_warning(
+    app: sphinx.application.Sphinx,
+    domain: sphinx.domains.Domain,
+    node: sphinx.addnodes.pending_xref,
+) -> bool | None:
+    """
+    Emitted when a cross-reference to an object cannot be resolved even
+    after missing-reference. If the event handler can emit warnings for the
+    missing reference, it should return True. The configuration variables
+    nitpick_ignore and nitpick_ignore_regex prevent the event from being
+    emitted for the corresponding nodes.
+    """
+    if domain and domain.name != 'py':
+        return None
+
+    from docutils.utils import get_source_line
+
+    source, line = get_source_line(node)
+    if 'docstring of collections.abc.' in source:
+        # Silence warnings that come from collections.abc
+        return True
+
+    return False
+
+
+def setup(app: sphinx.application.Sphinx) -> dict[str, bool | str]:
+    app.connect('warn-missing-reference', handle_ref_warning)
+
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

src/rez/build_system.py

@@ -28,7 +28,7 @@ def get_valid_build_systems(working_dir, package=None):
             must be present for the 'custom' build system type.
 
     Returns:
-        List of class: Valid build system class types.
+        list[type[BuildSystem]]: Valid build system class types.
     """
     from rez.plugin_managers import plugin_manager
     from rez.exceptions import PackageMetadataError
@@ -221,16 +221,17 @@ def build(self, context, variant, build_path, install_path, install=False,
             build_type: A BuildType (i.e local or central).
 
         Returns:
-            A dict containing the following information:
+            dict: A dict containing the following information:
+
             - success: Bool indicating if the build was successful.
             - extra_files: List of created files of interest, not including
-                build targets. A good example is the interpreted context file,
-                usually named 'build.rxt.sh' or similar. These files should be
-                located under build_path. Rez may install them for debugging
-                purposes.
+              build targets. A good example is the interpreted context file,
+              usually named 'build.rxt.sh' or similar. These files should be
+              located under build_path. Rez may install them for debugging
+              purposes.
             - build_env_script: If this instance was created with write_build_scripts
-                as True, then the build should generate a script which, when run
-                by the user, places them in the build environment.
+              as True, then the build should generate a script which, when run
+              by the user, places them in the build environment.
         """
         raise NotImplementedError
 

src/rez/package_cache.py

@@ -149,7 +149,7 @@ def add_variant(self, variant, force=False):
                 is no guarantee the resulting variant payload will be functional).
 
         Returns:
-            2-tuple:
+            tuple: 2-tuple:
             - str: Path to cached payload
             - int: One of VARIANT_FOUND, VARIANT_CREATED, VARIANT_COPYING, VARIANT_COPY_STALLED
         """
@@ -477,7 +477,8 @@ def get_variants(self):
         """Get variants and their current statuses from the cache.
 
         Returns:
-            List of 3-tuple:
+            tuple: List of 3-tuple:
+
             - `Variant`: The cached variant
             - str: Local cache path for variant, if determined ('' otherwise)
             - int: Status. One of:

src/rez/package_copy.py

@@ -31,41 +31,43 @@ def copy_package(package, dest_repository, variants=None, shallow=False,
     """Copy a package from one package repository to another.
 
     This copies the package definition and payload. The package can also be
-    re-named and/or re-versioned using the `dest_name` and `dest_version` args.
+    re-named and/or re-versioned using the ``dest_name`` and ``dest_version`` args.
 
     The result is a dict describing which package variants were and were not
     copied. For example:
 
-        {
-            "copied": [
-                (`Variant`, `Variant`)
-            ],
-            "skipped": [
-                (`Variant`, `Variant`)
-            ]
-        }
+    .. code-block:: text
+
+       {
+           "copied": [
+               (`Variant`, `Variant`)
+           ],
+           "skipped": [
+               (`Variant`, `Variant`)
+           ]
+       }
 
     Each 2-tuple in the 'copied' or 'skipped' list contains the source and
     destination variant respectively. In the 'skipped' list, the source variant
     is the variant that was NOT copied, and the dest variant is the existing
     target variant that caused the source not to be copied. Skipped variants
     will only be present when `overwrite` is False.
 
-    Note:
-        Whether or not a package can be copied is determined by its 'relocatable'
-        attribute (see the `default_relocatable` config setting for more details).
-        An attempt to copy a non-relocatable package will fail. You can override
-        this behaviour with the `force` argument.
+    .. note::
+       Whether or not a package can be copied is determined by its :attr:`relocatable`
+       attribute (see the :data:`default_relocatable` config setting for more details).
+       An attempt to copy a non-relocatable package will fail. You can override
+       this behaviour with the ``force`` argument.
 
     Args:
-        package (`Package`): Package to copy.
-        dest_repository (`PackageRepository` or str): The package repository, or
+        package (Package): Package to copy.
+        dest_repository (PackageRepository or str): The package repository, or
             a package repository path, to copy the package into.
-        variants (list of int): Indexes of variants to build, or all if None.
+        variants (list[int]): Indexes of variants to build, or all if None.
         shallow (bool): If True, symlinks of each variant's root directory are
             created, rather than the payload being copied.
         dest_name (str): If provided, copy the package to a new package name.
-        dest_version (str or `Version`): If provided, copy the package to a new
+        dest_version (str or Version): If provided, copy the package to a new
             version.
         overwrite (bool): Overwrite variants if they already exist in the
             destination package. In this case, the existing payload is removed
@@ -81,7 +83,7 @@ def copy_package(package, dest_repository, variants=None, shallow=False,
             is kept intact. Note that this will have no effect if variant(s)
             are copied into an existing package.
         skip_payload (bool): If True, do not copy the package payload.
-        overrides (dict): See `PackageRepository.install_variant`.
+        overrides (dict): See :meth:`.PackageRepository.install_variant`.
         verbose (bool): Verbose mode.
         dry_run (bool): Dry run mode. Dest variants in the result will be None
             in this case.