Improve docs build and Sphinx configuration

Add _set_module_for_docs to fix cross-reference resolution, improve
autodoc member filtering, linkcode for dataclass fields, and add
backend deps to docs extra.

Author: isarandi

.readthedocs.yaml

@@ -5,6 +5,7 @@ build:
   tools:
     python: "3.10"
   commands:
+    - python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
     - python -m pip install ".[docs]"
     - python -m sphinx -E -b html docs $READTHEDOCS_OUTPUT/html
 

docs/conf.py

@@ -139,32 +139,51 @@
 
 
 def autodoc_skip_member(app, what, name, obj, skip, options):
-    """Skip members (functions, classes, modules) without docstrings."""
+    """Skip members without docstrings or from undocumented modules."""
     if not getattr(obj, 'docstring', None):
         return True
     elif what in ('class', 'function', 'attribute'):
-        # Check if the module of the class has a docstring
         module_name = '.'.join(name.split('.')[:-1])
         try:
-            module = importlib.import_module(module_name)
-            return not getattr(module, '__doc__', None)
+            mod = importlib.import_module(module_name)
+            if not getattr(mod, '__doc__', None):
+                return True  # Module has no docstring, skip its members
         except ModuleNotFoundError:
+            # Import failed (e.g. attribute path like Class.attr, or missing dep).
+            # Defer to AutoAPI default.
             return None
+        # For private names, defer to AutoAPI default (which skips them).
+        # For public names, force-include (overrides the imported-members default).
+        short_name = name.split('.')[-1]
+        if short_name.startswith('_') and not short_name.startswith('__'):
+            return None
+        return False
     return skip
 
 
 def linkcode_resolve(domain, info):
     if domain != 'py':
         return None
 
+    fullname = info['fullname']
     try:
-        obj = eval(info['fullname'], module.__dict__)
-        file, start, end = get_line_numbers(obj)
-        relpath = os.path.relpath(file, os.path.dirname(module.__file__))
-        return f'{repo_url}/blob/v{release}/src/{main_module_name}/{relpath}#L{start}-L{end}'
-    except Exception:
+        file, start, end = get_line_numbers(eval(fullname))
+    except AttributeError:
+        # Instance attribute (dataclass field or self.x = ... in __init__)
+        parts = fullname.rsplit('.', 1)
+        if len(parts) != 2:
+            return None
+        try:
+            file, start, end = get_attr_line_numbers(eval(parts[0]), parts[1])
+        except Exception:
+            return None
+    except Exception as e:
+        print(f'linkcode_resolve failed: {info} — {e}')
         return None
 
+    relpath = os.path.relpath(file, os.path.dirname(module.__file__))
+    return f'{repo_url}/blob/v{release}/src/{main_module_name}/{relpath}#L{start}-L{end}'
+
 
 def get_line_numbers(obj):
     if isinstance(obj, property):
@@ -196,6 +215,22 @@ def get_enum_member_line_numbers(obj):
             raise ValueError(f'Enum member {obj.name} not found in {class_}')
 
 
+def get_attr_line_numbers(class_, attr_name):
+    with module_restored(class_):
+        source_lines, start_line = inspect.getsourcelines(class_)
+        for i, line in enumerate(source_lines):
+            stripped = line.strip()
+            if (
+                stripped.startswith(f'{attr_name}:')
+                or stripped.startswith(f'{attr_name} :')
+                or f'self.{attr_name} =' in stripped
+                or f'self.{attr_name}=' in stripped
+            ):
+                return inspect.getsourcefile(class_), start_line + i, start_line + i
+        else:
+            raise ValueError(f'Attribute {attr_name} not found in {class_}')
+
+
 def get_member_line_numbers(obj: types.MemberDescriptorType):
     class_ = obj.__objclass__
     with module_restored(class_):

pyproject.toml

@@ -74,6 +74,11 @@ docs = [
     "pydata-sphinx-theme",
     "setuptools-scm",
     "toml",
+    "torch",
+    "tensorflow",
+    "jax",
+    "jaxlib",
+    "numba",
 ]
 dev = ["smplfitter[test,lint,docs,pytorch]"]
 

src/smplfitter/__init__.py

@@ -10,11 +10,12 @@
 
 from __future__ import annotations
 
-from .common import ModelData, initialize
+from .common import ModelData, initialize, _set_module_for_docs
 
 try:
     from ._version import version as __version__
 except ImportError:
     __version__ = '0.0.0'
 
 __all__ = ['ModelData', 'initialize', '__version__']
+_set_module_for_docs(__name__, globals(), __all__)

src/smplfitter/common.py

@@ -11,6 +11,22 @@
 import numpy as np
 
 
+def _set_module_for_docs(module_name, module_globals, all_names):
+    """Override __module__ on exported objects so Sphinx resolves package-level names.
+
+    sphinx-codeautolink uses __module__ to find the docs page for a name. Without this,
+    e.g. ``BodyModel`` imported from ``smplfitter.pt.bodymodel`` would not link to
+    ``smplfitter.pt.BodyModel``. The original __module__ is saved as ``_module_original_``
+    so that ``inspect.getsourcefile`` can still find the real source file (see
+    ``module_restored`` in docs/conf.py).
+    """
+    for name in all_names:
+        obj = module_globals.get(name)
+        if obj is not None and callable(obj):
+            obj._module_original_ = obj.__module__
+            obj.__module__ = module_name
+
+
 @dataclass
 class ModelData:
     """Data loaded from a SMPL-family body model file.

src/smplfitter/jax/__init__.py

@@ -9,8 +9,10 @@
 from .bodyfitter import BodyFitter
 from .bodyconverter import BodyConverter
 from . import rotation
+from smplfitter.common import _set_module_for_docs
 
 __all__ = ['BodyModel', 'BodyFitter', 'BodyConverter', 'get_cached_body_model', 'rotation']
+_set_module_for_docs(__name__, globals(), __all__)
 
 
 @functools.lru_cache()

src/smplfitter/nb/__init__.py

@@ -9,8 +9,10 @@
 from .bodyfitter import BodyFitter
 from .bodyconverter import BodyConverter
 from . import rotation
+from smplfitter.common import _set_module_for_docs
 
 __all__ = ['BodyModel', 'BodyFitter', 'BodyConverter', 'get_cached_body_model', 'rotation']
+_set_module_for_docs(__name__, globals(), __all__)
 
 
 @functools.lru_cache()

src/smplfitter/np/__init__.py

@@ -5,11 +5,13 @@
 from .bodymodel import BodyModel
 from .bodyfitter import BodyFitter
 from .bodyconverter import BodyConverter
+from smplfitter.common import _set_module_for_docs
 
 import functools
 import os
 
 __all__ = ['BodyModel', 'BodyFitter', 'BodyConverter', 'get_cached_body_model']
+_set_module_for_docs(__name__, globals(), __all__)
 
 
 @functools.lru_cache()

src/smplfitter/pt/__init__.py

@@ -12,6 +12,7 @@
 from .bodyfitter import BodyFitter
 from .bodyconverter import BodyConverter
 from .bodyflipper import BodyFlipper
+from smplfitter.common import _set_module_for_docs
 
 
 __all__ = [
@@ -23,6 +24,7 @@
     'get_cached_fit_fn',
     'fit',
 ]
+_set_module_for_docs(__name__, globals(), __all__)
 
 
 @functools.lru_cache()

src/smplfitter/tf/__init__.py

@@ -9,6 +9,7 @@
 from .bodymodel import BodyModel
 from .bodyfitter import BodyFitter
 from .bodyconverter import BodyConverter
+from smplfitter.common import _set_module_for_docs
 
 __all__ = [
     'BodyModel',
@@ -17,6 +18,7 @@
     'get_cached_body_model',
     'get_cached_fit_fn',
 ]
+_set_module_for_docs(__name__, globals(), __all__)
 
 
 @functools.lru_cache()