DOCS: Render API methods inline via custom autosummary templates (#847)

docs/_config.yml

@@ -43,6 +43,8 @@ sphinx:
     linkcode: _ext
   config:
     autosummary_generate: True
+    templates_path: ['_templates']
+    numpydoc_show_class_members: False
     bibtex_reference_style: author_year
 
 parse:

docs/_ext/linkcode.py

@@ -53,19 +53,33 @@ def linkcode_resolve(domain: str, info: dict) -> str | None:
     for part in info["fullname"].split("."):
         obj: type = getattr(obj, part)
 
+    # Resolve properties to their underlying getter function.
+    if isinstance(obj, property):
+        obj = obj.fget
+        if obj is None:
+            return None
+
     # Unwrap any decorators.
     obj: type = inspect.unwrap(obj)
 
-    # Get the path of the source file.
-    source_file: str = inspect.getsourcefile(obj)
+    # Get the path of the source file. Some objects (e.g. C-level callables or
+    # dynamically created members) are not introspectable; skip linking those.
+    try:
+        source_file: str = inspect.getsourcefile(obj)
+    except TypeError:
+        return None
 
     # If the source file cannot be found, return the URL pointing to a .py file named after the module.
     if source_file is None:
         filename: str = info["module"].replace(".", "/")
         return url_base + "%s.py" % filename
 
     # Extract the lines and locate the starting line position.
-    source_lines, start_line = inspect.getsourcelines(obj)
+    try:
+        source_lines, start_line = inspect.getsourcelines(obj)
+    except (TypeError, OSError):
+        filename: str = info["module"].replace(".", "/")
+        return url_base + "%s.py" % filename
 
     # Get the root path.
     root_path: str = os.path.abspath(os.path.join(cl.__file__, "..", ".."))

docs/_templates/autosummary/class.rst

@@ -0,0 +1,8 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/_templates/autosummary/class_inherited.rst

@@ -0,0 +1,9 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :inherited-members:
+   :show-inheritance:

docs/_templates/autosummary/function.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}

docs/conf.py

@@ -40,5 +40,7 @@
 numfig = True
 pygments_style = 'sphinx'
 suppress_warnings = ['myst.domains']
+templates_path = ['_templates']
+numpydoc_show_class_members = False
 use_jupyterbook_latex = True
 use_multitoc_numbering = True

docs/library/api.md

@@ -20,7 +20,7 @@ Classes
 
 .. autosummary::
   :toctree: generated/
-  :template: class_inherited.rst
+  :template: class_inherited
 
   Triangle
   DevelopmentCorrelation
@@ -43,7 +43,7 @@ Classes
 
 .. autosummary::
   :toctree: generated/
-  :template: class.rst
+  :template: class
 
   Development
   DevelopmentConstant
@@ -72,7 +72,7 @@ Classes
 
 .. autosummary::
   :toctree: generated/
-  :template: class.rst
+  :template: class
 
   TailConstant
   TailCurve
@@ -96,7 +96,7 @@ Classes
 
 .. autosummary::
    :toctree: generated/
-   :template: class.rst
+   :template: class
 
    Chainladder
    MackChainladder
@@ -119,7 +119,7 @@ Classes
 
 .. autosummary::
  :toctree: generated/
- :template: class.rst
+ :template: class
 
  BootstrapODPSample
  BerquistSherman
@@ -140,7 +140,7 @@ Classes
 
 .. autosummary::
   :toctree: generated/
-  :template: class.rst
+  :template: class
 
   Pipeline
   VotingChainladder
@@ -162,7 +162,7 @@ Functions
 
 .. autosummary::
    :toctree: generated/
-   :template: function.rst
+   :template: function
 
    load_sample
    read_pickle
@@ -178,7 +178,7 @@ Classes
 
 .. autosummary::
  :toctree: generated/
- :template: class.rst
+ :template: class
 
  PatsyFormula