docs: add Triangle arithmetic examples (#704)

[EKtheSage]

Summary of Changes

• Add doctest Examples for Triangle.__add__, .__sub__, .__mul__, and .__truediv__ in chainladder/core/dunders.py.
• Include __add__ / __sub__ / __mul__ / __truediv__ as special-members on the inherited-class autosummary template so the operators appear on the Triangle API page.
• Cover scalar arithmetic and column-ratio division (paid / incurred).

Related GitHub Issue(s)

• API Reference Examples #704

Additional Context for Reviewers

Bite-sized core-module follow-up for #704. Companions: #1208 (slice), #1209 (io), #1210 (display).

Checklist

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

Made with Cursor

[github-actions]

Pyright Type Completeness

View the full pyright --verifytypes output for this commit

Project (full chainladder package, at this PR's head): 15.1% of exported symbols fully typed (201 / 1333)

	Known	Ambiguous	Unknown	Total
Project (head)	201	111	1021	1333

Other symbols referenced but not exported by chainladder: 13

	Known	Ambiguous	Unknown	Total
Other (head)	3	1	9	13

Symbols without documentation:

• Functions without docstring: 321
• Functions without default param: 0
• Classes without docstring: 10

Patch (exported symbols added or changed by this PR): no exported symbol type-completeness changes detected.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.26%. Comparing base (52e655b) to head (5dc1bf7).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1213   +/-   ##
=======================================
  Coverage   91.26%   91.26%           
=======================================
  Files          91       91           
  Lines        5401     5401           
  Branches      691      691           
=======================================
  Hits         4929     4929           
  Misses        338      338           
  Partials      134      134           

Flag	Coverage Δ
unittests	91.26% <ø> (ø)

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

☔ View full report in Codecov by Harness.
📢 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.

[henrydingliu]

should tri be in testcode instead?

[EKtheSage]

Moved. testsetup is only import chainladder as cl; the Triangle is built in testcode.

[henrydingliu]

macro comment. i don't see __add__ listed in pandas. instead, there is an equivalent dataframe function .add.

@kennethshsu @genedan @priyam0k should we follow pandas?

[EKtheSage]

On following pandas DataFrame.add: Triangle has no .add / .sub / .mul / .div. The operators are the public arithmetic API, so :special-members: is how those examples show up on the Triangle page.

Leaving whether to add pandas-style .add methods to the people tagged above.

[henrydingliu]

On following pandas DataFrame.add: Triangle has no .add / .sub / .mul / .div. The operators are the public arithmetic API, so :special-members: is how those examples show up on the Triangle page.

Leaving whether to add pandas-style .add methods to the people tagged above.

yeah, that's what I mean, taking inspiration from your other PR on slice.py

[genedan]

I think these examples are useful. I think dunders and arithmetic operators fall under "advanced programming for actuaries" territory, so it'd be helpful for them to see how the operators are related to the dunders, and how we program them into the package.

[priyam0k]

Agree with Gene. Documenting dunders makes sense here since operators are Triangle's current arithmetic API.

The main benefit of pandas .add() would be supporting fill_value for mismatched triangles, but we can track .add() in a separate feature issue if needed.