[DOCS] Templates for API Reference by henrydingliu · Pull Request #893 · casact/chainladder-python

henrydingliu · 2026-05-31T18:14:03Z

Summary of Changes

Docs-only; no runtime, config, or public API changes.

Clean-up
- Deletes the 36 .rst stub files under docs/library/generated/.
- Adds docs/library/generated/ to .gitignore, mirroring the existing docs/modules/generated/ entry one line above.
- These files are emitted by sphinx.ext.autosummary on every docs build (autosummary_generate = True in docs/conf.py, driven by the eight :toctree: generated/ directives in docs/library/api.md), so committing them is redundant and the committed copies drift out of sync with what Sphinx actually produces.
Adds custom sphinx.ext.autosummary templates under docs/_templates/autosummary/: class.rst, class_inherited.rst, function.rst.
- API class pages now list own methods inline, and inherited methods in a summary table (via Jinja logic in the templates)
- Fixes the :template: names in docs/library/api.md to drop .rst (:template: class.rst → :template: class).
- Sets numpydoc_show_class_members = False and templates_path = ['_templates'] in docs/_config.yml (and the generated docs/conf.py).
- Guards docs/_ext/linkcode.py against property objects so inline members don't crash the build.
  - properties since removed. will keep this redundancy in place
Misc docstring bug fixes, from doctest warnings

Three issues fixed along the way:

:template: class.rst never worked. Sphinx appends .rst, so it looked for autosummary/class.rst.rst and fell back to the base template. Names now omit the extension.
numpydoc duplicate table. numpydoc_show_class_members = False stops numpydoc emitting its own members table next to the inline members.
linkcode_resolve crash. Inline members pass property objects to the resolver, where inspect.getsourcefile(property) raises TypeError and aborts jb build. Fixed by unwrapping properties to fget and guarding getsourcefile / getsourcelines.

Related GitHub Issue(s)

closes #887
closes #846
closes #847
partially addresses #888

Additional Context for Reviewers

conf.py is regenerated from _config.yml by Jupyter Book; both updated to stay in sync.
jb build . succeeds (warnings all pre-existing). HTML spot checks:
Page | Inline methods | Inline properties | numpydoc table -- | -- | -- | -- Development (class) | 3 | 0 | none Triangle (class_inherited) | 64 | 24 | none load_sample (function) | function block | – | –

I passed tests locally for both code (uv run pytest) and documentation changes (uv run jb build docs --builder=custom --custom-builder=doctest)

Note

Low Risk
Changes are limited to documentation build, templates, and docstrings; no runtime or estimator logic is modified.

Overview
This PR is docs-only for the API reference and user guide; it does not change reserving behavior or public Python APIs.

API reference build: Committed autosummary stubs under docs/library/generated/ are removed and that path is gitignored so Sphinx regenerates them on each build. Custom autosummary templates (class, class_inherited, function) list class members inline and inherited methods in a separate summary table; docs/library/api.md :template: values drop the .rst suffix so Sphinx resolves templates correctly. numpydoc_show_class_members = False and templates_path are set in docs/_config.yml and docs/conf.py to avoid duplicate member tables.

Linkcode: docs/_ext/linkcode.py now skips missing attributes, unwraps property to fget, and guards getsourcefile / getsourcelines so API pages do not abort the Jupyter Book build.

User guide / misc: User guide cards and one MackChainladder example switch from glue: figures to static ../images/*.png; methods.ipynb uses a grid card for the Mack gallery link. Small docstring fixes in chainladder/core/pandas.py, incremental.py, and capecod.py; one bibliography URL update in references.bib.

^{Reviewed by Cursor Bugbot for commit 19f5598. Bugbot is set up for automated code reviews on this repo. Configure here.}

playing around with rst

adding the rst to toc

not fixing https://github.com/casact/chainladder-python/actions/runs/26704888295/job/78704117793#step:5:287

attempting to fix https://github.com/casact/chainladder-python/actions/runs/26704888295/job/78704117793#step:5:271

attempting to fix https://github.com/casact/chainladder-python/actions/runs/26705264841/job/78705209125#step:5:283

attempting another fix of https://github.com/casact/chainladder-python/actions/runs/26706024696/job/78707335590#step:5:282

@henrydingliu

* Improved docstring and added examples * Added the link ratios * docs: add doctest examples for correlation classes Adds Sphinx doctest Examples sections to DevelopmentCorrelation and ValuationCorrelation. Each example opens with the Mack chain-ladder assumption being tested, prints the full decision signal (statistic, confidence band, and boolean) rather than a single boolean, and ties the result back to the chain-ladder workflow. Refs #704 * docs: add BootstrapODPSample doctest examples Adds Sphinx doctest Examples section to the BootstrapODPSample class showing basic fit (resampled_triangles_.shape and scale_), downstream stochastic IBNR via Chainladder, and the effect of drop_high on scale_. Uses random_state=42 and n_sims=100 for deterministic, fast output. Refs #704 * docs: reframe drop_high example as sensitivity check Rewords the paragraph introducing the drop_high=True example to describe it as a leave-one-out sensitivity check on the column maxima rather than outlier removal, since drop_high mechanically removes the column max without any outlier test. Addresses review feedback on #836. * docs: move per-diagonal vs total mode note between testcode blocks Per @henrydingliu review on #844: opening paragraph now scoped to the calendar-effect concept; the per-diagonal vs whole-triangle distinction is introduced as a transition between the two testcode blocks. Refs #704 * docs: add README documenting docs build sources and outputs (refs #845) * Added the transformed link ratio triangle using fit_transform to examples * Removed the multiple testouputs * docs: address review feedback on docs README (refs #845) - Drop the jb build internals + duplicate warnings note (kennethshsu) - Rename 'tutorial notebooks' to 'onboarding and Quickstart notebooks' (kennethshsu) - Drop the 'What to edit for which part of the site' table and 'Known issues' section as redundant with the Source files table and #841 (kennethshsu) * [REFACTOR]: Remove repetitive code. Remove dead Python 3.8 code. Add missing unit tests. * [FIX]: Limit test to only those values meant to be changed. Use realistic values for changed options. * [DOCS]: Finish updating Options docstring. * [FIX]: Fix ending state of test. * [FIX]: Reset backend after sparse-only run. * [REFACTOR] Create template fixture for sample data sets. * [Fix]: Remove duplicate fixture. * [REFACTOR]: Move datetime defaults out of Options. Add validation to option getters and setters. Deprecate cl.array_backend() and cl.auto_sparse() * FIX: Apply Bugbot fix. * FIX: Apply Bugbot fix. * FIX: Apply Bugbot fix. * DOCS: Add docstring, clean up test. * DOCS: Update docstring. * Friedland Chapter 6 and half of Chapter 7 (#837) first batch of deliverables for friedland reconstruction * Delete docs/library/generated/chainladder.Development.rst --------- Co-authored-by: Kenneth Hsu <kennethshsu@gmail.com> Co-authored-by: priyam0k <87162535+priyam0k@users.noreply.github.com> Co-authored-by: Gene Dan <genedan@gmail.com>

fixing https://github.com/casact/chainladder-python/actions/runs/26706024696/job/78707335590#step:5:281

codecov · 2026-05-31T18:19:15Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.21%. Comparing base (449b5c1) to head (19f5598).
⚠️ Report is 28 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #893      +/-   ##
==========================================
+ Coverage   87.04%   87.21%   +0.17%     
==========================================
  Files          86       87       +1     
  Lines        4986     5344     +358     
  Branches      646      749     +103     
==========================================
+ Hits         4340     4661     +321     
- Misses        456      480      +24     
- Partials      190      203      +13

Flag	Coverage Δ
unittests	`87.18% <ø> (+0.13%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

- Drop :show-inheritance: from the class templates so internal base classes (e.g. MethodBase behind Chainladder) are no longer listed. - Add :inherited-members: to the plain class template so useful inherited methods like to_pickle appear on pages such as Development.

Adding :inherited-members: to the class template surfaces members like Pipeline.steps that exist on instances but not on the class object, so linkcode's getattr walk raised AttributeError and aborted the build. Skip linking those members instead.

henrydingliu · 2026-06-01T19:38:42Z

@kennethshsu I plan on moving this out of draft ASAP. One more small link bug to fix with Priyam's help. But majority of the PR is ready for review. Given the size of this PR looks daunting (50 diff files), I'd like to put it in front of you now while we get that last bug worked out.

the motivation for this PR is twofold.

the autosummary table of methods was generating a ton of doctest warnings. this PR eliminiates all the stub warning and just a handful remains.
the autosummary table was masking all additional docstrings at the individual method level. compare the new to the old.

long term, the custom templates that's introduced to solve item No. 2 will enable us to have much more control over the api reference.

cursor

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 19f5598. Configure here.}

cursor · 2026-06-01T22:11:51Z

-    "```{glue:} plot_mack\n",
+    ":::{grid-item-card}\n",
+    ":columns: 4\n",
+    ":link: ...gallery/plot_mack\n",    


Broken doc link uses three dots instead of two

Medium Severity

The :link: value ...gallery/plot_mack has three dots with no separating slash, making it an invalid relative doc reference. Every other grid-item-card link in the codebase (e.g. in development.ipynb) uses the correct two-dot-slash pattern ../gallery/.... This will produce a broken link on the MackChainladder examples card.

^{Reviewed by Cursor Bugbot for commit 19f5598. Configure here.}

ignoring. will fix in a future PR

cursor · 2026-06-01T22:11:51Z

+    ":link: ...gallery/plot_mack\n",    
+    ":link-type: doc\n",        
+    "**[MackChainladder Basics]**\n",
+    "```{image} ../images/plot_mack.png\n",


Grid directive never closed, citations rendered inside grid

Medium Severity

The ::::{grid} directive opened at line 529 is never closed with a matching ::::. The ::: at line 542 only closes the inner :::{grid-item-card}. This leaves the {cite} references trapped inside the unclosed grid and may cause rendering issues. Every other grid in development.ipynb properly closes with :::: before placing citations outside.

^{Reviewed by Cursor Bugbot for commit 19f5598. Configure here.}

ignoring. will fix in a future PR

cursor · 2026-06-01T22:11:51Z

+{% for method in inherited %}
+   {{ objname }}.{{ method }}
+{% endfor %}
+{% endif %}


Two autosummary templates are completely identical files

Low Severity

class.rst and class_inherited.rst are byte-for-byte identical. The class_inherited template is used for Triangle and correlation classes (presumably to show inherited members inline), but it lacks :inherited-members: in its autoclass directive. Either the template needs to differ from class.rst (e.g. by adding :inherited-members:) or one of the two files is redundant.

Additional Locations (1)

docs/_templates/autosummary/class.rst#L1-L26

^{Reviewed by Cursor Bugbot for commit 19f5598. Configure here.}

intentional. will vary in the future

kennethshsu · 2026-06-01T23:41:15Z

How much of this has been reviewed? @henrydingliu I think you reviewed a lot of these already right (as in you are not the original author)?

henrydingliu · 2026-06-01T23:58:40Z

How much of this has been reviewed? @henrydingliu I think you reviewed a lot of these already right (as in you are not the original author)?

great question.

changes authored by @priyam0k and already reviewed by me

linkcode.py
function.rst
api.md
_config.yml
conf.py
all of the stub file deletions

files that @priyam0k and I both worked on

class.rst
class_inherited.rst

these templates are the most impactful changes. to review, less so functionally, but maybe more stylistically/look-&-feel. i would recommend looking through a handful of classes in the api reference, particularly the heavy-hitting ones like triangle and development. comparing the experimental version and the main side by side is probably helpful too. the balance i tried to strike at the end is maintain all inherited methods in a summary table (just like before) but allowing the class methods to show the full docstring.

i would also say that with custom templates, nothing is a one-way door, i.e. we can change the layout anytime. but i wanted another set of eyes to make sure there's not some glaring oversight that we need to immediately address.

doc fixes I've making here and there to reduce doctest warnings. these are low impact

method.ipynb
user_guide/index.md
references.bib
pandas.py
incremental.py
capecod.py

henrydingliu added 30 commits May 7, 2026 22:27

Create Chapter_7.rst

d9b475d

playing around with rst

Update _toc.yml

52aa870

adding the rst to toc

Update conf.py

6b898b9

Update conf.py

495dc07

Update Chapter_7.rst

959ca09

Update Chapter_7.rst

80e04e7

Update conf.py

6594d2e

Update pyproject.toml

4008bbd

Update Chapter_7.rst

4f32339

Update conf.py

08a4e13

Update pyproject.toml

f6ce731

Update conf.py

3d4356a

Update _config.yml

c6d01b8

Update _config.yml

f1085a2

Update conf.py

c3997bf

Update pyproject.toml

9e6afa1

Update Chapter_7.rst

fa306dc

Update pyproject.toml

160ebf3

Update pyproject.toml

c3621e4

Update _config.yml

2fd2d2a

Update conf.py

227fd8d

Update Chapter_7.rst

1d41c57

Update conf.py

a00d3d2

Update conf.py

dd3c488

Update _config.yml

90e70a6

Update Chapter_7.rst

77f59fd

Update Chapter_7.rst

a89501f

Update Chapter_7.rst

1f6c2af

Update Chapter_7.rst

2539307

Update Chapter_7.rst

4fe415f

henrydingliu and others added 12 commits May 30, 2026 23:11

Update README.md

e3d9c35

not fixing https://github.com/casact/chainladder-python/actions/runs/26704888295/job/78704117793#step:5:287

Update _toc.yml

82c88d5

Update api.md

d83b8ab

Update index.md

75d24b0

attempting to fix https://github.com/casact/chainladder-python/actions/runs/26704888295/job/78704117793#step:5:271

Update index.md

6f0217b

attempting to fix https://github.com/casact/chainladder-python/actions/runs/26705264841/job/78705209125#step:5:283

Update index.md

64dec23

Update methods.ipynb

fbdfc2f

attempting another fix of https://github.com/casact/chainladder-python/actions/runs/26706024696/job/78707335590#step:5:282

Create chainladder.Development.rst

fdb2d04

Update index.md

170e611

fixing https://github.com/casact/chainladder-python/actions/runs/26706024696/job/78707335590#step:5:281

Delete docs/library/generated/chainladder.Development.rst

b9ec940

Update index.md

0b26dd3

priyam0k and others added 6 commits June 1, 2026 07:17

Update class.rst

a1dbaa2

Update class_inherited.rst

9c5097f

Update class.rst

30232a2

Update class_inherited.rst

6c7855c

henrydingliu changed the title ~~Experimental~~ [DOCS] Templates for API Reference Jun 1, 2026

henrydingliu added 2 commits June 1, 2026 15:05

Update class.rst

eb4cf23

Update class_inherited.rst

19f5598

cursor Bot reviewed Jun 1, 2026

View reviewed changes

henrydingliu marked this pull request as ready for review June 1, 2026 22:16

henrydingliu requested review from genedan, jbogaardt and kennethshsu as code owners June 1, 2026 22:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Templates for API Reference#893

[DOCS] Templates for API Reference#893
henrydingliu wants to merge 170 commits into
mainfrom
experimental

henrydingliu commented May 31, 2026 •

edited by cursor Bot

Loading

Uh oh!

codecov Bot commented May 31, 2026 •

edited

Loading

Uh oh!

henrydingliu commented Jun 1, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Jun 1, 2026

Uh oh!

henrydingliu Jun 1, 2026

Uh oh!

cursor Bot Jun 1, 2026

Uh oh!

henrydingliu Jun 1, 2026

Uh oh!

cursor Bot Jun 1, 2026

Uh oh!

henrydingliu Jun 1, 2026

Uh oh!

kennethshsu commented Jun 1, 2026

Uh oh!

henrydingliu commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

henrydingliu commented May 31, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of Changes

Related GitHub Issue(s)

Additional Context for Reviewers

Uh oh!

codecov Bot commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

henrydingliu commented Jun 1, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 1, 2026

Choose a reason for hiding this comment

Broken doc link uses three dots instead of two

Uh oh!

henrydingliu Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 1, 2026

Choose a reason for hiding this comment

Grid directive never closed, citations rendered inside grid

Uh oh!

henrydingliu Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 1, 2026

Choose a reason for hiding this comment

Two autosummary templates are completely identical files

Uh oh!

henrydingliu Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

kennethshsu commented Jun 1, 2026

Uh oh!

henrydingliu commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

henrydingliu commented May 31, 2026 •

edited by cursor Bot

Loading

codecov Bot commented May 31, 2026 •

edited

Loading