[DOCS] Templates for API Reference

.gitignore

@@ -69,6 +69,7 @@ instance/
 docs/_build/
 docs/auto_examples/
 docs/modules/generated/
+docs/library/generated/
 
 # PyBuilder
 target/

chainladder/core/pandas.py

@@ -72,6 +72,7 @@ def to_frame(
             **kwargs
     ) -> DataFrame | Series:
         """ Converts a triangle to a pandas.DataFrame.
+
         Parameters
         ----------
         origin_as_datetime : bool
@@ -84,9 +85,10 @@ def to_frame(
         implicit_axis : bool
             When keepdims is True, this denotes whether to include the implicit
             valuation axis in addition to the origin and development.
+
         Returns
         -------
-            DataFrame or Series representation of the Triangle.
+        DataFrame or Series representation of the Triangle.
         """
 
         # Identify the axes that increase the dimensionality of the triangle, i.e., those whose length is > 1.
@@ -204,7 +206,7 @@ def _get_axis(axis: str | int| None) -> int:
             supplied as a string, returns the integer representation. If
             supplied as an integer, returns the same integer.
 
-        Returns`
+        Returns
         -------
         The integer representation of the requested axis
 
@@ -252,6 +254,7 @@ def dropna(self):
 
     def fillna(self, value=None, inplace=False):
         """Fill nan with 'value' by axis.
+
         Parameters
         ----------
         value: single value or array-like values, default = None
@@ -277,6 +280,7 @@ def fillna(self, value=None, inplace=False):
 
     def fillzero(self, inplace=False):
         """Fill nan with 0 by axis. separate function from fillna() because fillna(0) isn't working
+
         Parameters
         ----------
         inplace: boolean, default = False
@@ -457,9 +461,11 @@ def xs(
         level:IndexLabel | None = None,
         drop_level:bool = True):
         '''
-        mimics xs from pandas. key difference
-            - this function only slides the index, therefore axis is always 0 and not an argument in the function
-        main use case for this function is when slicing beyond the first field in the index (such as LOB in the clrd dataset)
+        Mimics xs from pandas. key difference is that  this function only slices 
+        the index, therefore axis is always 0 and not an argument in the function
+
+        Main use case for this function is when slicing beyond the first field in 
+        the index (such as LOB in the clrd dataset)
         '''
         mi = pd.MultiIndex.from_frame(self.index)
 

chainladder/development/incremental.py

@@ -62,7 +62,7 @@ class IncrementalAdditive(DevelopmentBase):
     w_: ndarray
         The weight used in the zeta fitting
     w_tri_: Triangle
-        Triangle of w_
+        Triangle of w\_
     sample_weight: Triangle
         The exposure used to obtain incremental factor
     incremental_: Triangle

chainladder/methods/capecod.py

@@ -18,11 +18,11 @@ class CapeCod(Benktander):
     decay: float, optional (default=1.0)
         The cape cod decay assumption. This parameter is required by the 
         Generalized Cape Cod Method, as discussed in [Using Best Practices to
-         Determine a Best Reserve Estimate](https://www.casact.org/sites/default/files/database/forum_98fforum_struhuss.pdf) 
-         by Struzzieri and Hussian. As the `decay` factor approaches 1 
-         (the default value), the result approaches the traditional Cape Cod 
-         method. As the `decay` factor approaches 0, the result approaches 
-         the `Chainladder` method.
+        Determine a Best Reserve Estimate](https://www.casact.org/sites/default/files/database/forum_98fforum_struhuss.pdf) 
+        by Struzzieri and Hussian. As the `decay` factor approaches 1 
+        (the default value), the result approaches the traditional Cape Cod 
+        method. As the `decay` factor approaches 0, the result approaches 
+        the `Chainladder` method.
     n_iters: int, optional (default=1)
         Number of iterations to use in the Benktander model.
     groupby: str or list, optional (default=None)

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

@@ -49,23 +49,42 @@ def linkcode_resolve(domain: str, info: dict) -> str | None:
     mod: ModuleType = importlib.import_module(info["module"])
 
     obj: ModuleType = mod
-    # Extract the part.
+    # Extract the part. Some documented members (e.g. instance attributes pulled
+    # in via :inherited-members:) are not accessible on the object itself; skip
+    # linking those rather than crashing the build.
     for part in info["fullname"].split("."):
-        obj: type = getattr(obj, part)
+        try:
+            obj: type = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    # 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,26 @@
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :exclude-members: set_fit_request, set_score_request, set_transform_request, {{ attributes | join(', ') }}
+
+{% set inherited = [] %}
+{% for method in methods %}
+{% if method in inherited_members and not method.startswith('_') %}
+{% set _ = inherited.append(method) %}
+{% endif %}
+{% endfor %}
+
+{% if inherited %}
+.. rubric:: Inherited Methods
+
+.. autosummary::
+   :nosignatures:
+
+{% for method in inherited %}
+   {{ objname }}.{{ method }}
+{% endfor %}
+{% endif %}

docs/_templates/autosummary/class_inherited.rst

@@ -0,0 +1,26 @@
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :exclude-members: set_fit_request, set_score_request, set_transform_request, {{ attributes | join(', ') }}
+
+{% set inherited = [] %}
+{% for method in methods %}
+{% if method in inherited_members and not method.startswith('_') %}
+{% set _ = inherited.append(method) %}
+{% endif %}
+{% endfor %}
+
+{% if inherited %}
+.. rubric:: Inherited Methods
+
+.. autosummary::
+   :nosignatures:
+
+{% for method in inherited %}
+   {{ objname }}.{{ method }}
+{% endfor %}
+{% endif %}

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,8 +178,8 @@ Classes
 
 .. autosummary::
  :toctree: generated/
- :template: class.rst
+ :template: class
 
  PatsyFormula
 
-```
+```