docs: add doctest Examples for development estimators and Mack fixes#786
docs: add doctest Examples for development estimators and Mack fixes#786EKtheSage wants to merge 3 commits into
Conversation
On every push to main, GitHub Actions automatically merges main into docs/great-docs-prototype so the docs branch stays current with all code changes while keeping its doc-engine files intact.
…rectives Add Examples sections using .. testsetup::, .. testcode::, and .. testoutput:: for BarnettZehnwirth, ClarkLDF, IncrementalAdditive, TweedieGLM, and DevelopmentML. Place import chainladder in testsetup and other imports in testcode. Correct MackChainladder class and full_std_err_ docstrings to use double-colon directives and .. testoutput:: so Sphinx doctests run them. Co-authored-by: Cursor <cursoragent@cursor.com>
Restore original class Parameters/Attributes text from main. Add Examples with .. testsetup:: / .. testcode:: / .. testoutput:: showing how outputs change for ClarkLDF (growth, sample_weight, groupby), BarnettZehnwirth (formula vs PTF), IncrementalAdditive (shape and future_trend), TweedieGLM (design_matrix and power/link), DevelopmentML (fit_incrementals and weighted_step), and MackChainladder (Development averaging before fit). Fix class-level Mack doctest directives to use :: and repair full_std_err_ testoutput::; add blank line after testsetup in total_process_risk example. Co-authored-by: Cursor <cursoragent@cursor.com>
EKtheSage
requested review from
genedan,
henrydingliu,
jbogaardt and
kennethshsu
as code owners
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #786 +/- ##
==========================================
- Coverage 86.13% 86.09% -0.05%
==========================================
Files 86 86
Lines 4941 4925 -16
Branches 643 639 -4
==========================================
- Hits 4256 4240 -16
Misses 486 486
Partials 199 199
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 1df94ec. Configure here.
| git config user.email "github-actions[bot]@users.noreply.github.com" | ||
| git checkout docs/great-docs-prototype | ||
| git merge origin/main --no-edit -m "chore: sync main into docs/great-docs-prototype" | ||
| git push origin docs/great-docs-prototype |
There was a problem hiding this comment.
Unrelated workflow file included in docs-only PR
Medium Severity
A new CI workflow sync-main-to-docs.yml was added that automatically merges main into docs/great-docs-prototype on every push to main. This file is not mentioned in the PR description, which exclusively describes doctest and Sphinx directive changes. The workflow triggers on all pushes to main (not just docs-related ones), will fail without error handling if the target branch doesn't exist or merge conflicts arise, and represents a significant infrastructure change that warrants its own dedicated review.
Reviewed by Cursor Bugbot for commit 1df94ec. Configure here.
|
random question. do doctests contribute towards codecov? |
|
I think this PR is too large and should be broken up into smaller parts. I would at least break up some the docstrings and great docs into two. Also unit tests failing on dcostrings. |
Currently no, only pytests contribute towards codecov. I think there's a way though. |
Sorry about that, great docs should not be in here. That was a github action to update great-docs branch on my repo to sync with the main branch here. I can drop it. But other than that, the rest of the PR is docstrings examples updates. Do you want to break them into smaller PRs like Barnett, Mack, Clark etc? |
|
Hi @EKtheSage, for now I’d recommend separating out the Great Docs changes. Even with that split, the PR is still on the larger side. I’m okay with moving forward with the docstring improvements for the 6 methods in a single PR this time since they are all just examples, though I wouldn’t recommend doing this going forward. PRs should be kept as small as possible. That said, there is still a failing unit test. Do you mind taking a look and resolving it? Please also use the PR template if possible, and avoid duplicating PRs? :) Sorry, I know this can feel like a lot of red tape, but I’d really love to get this PR merged. Thanks so much for the energy and effort here. I’ll be happy to review the revision. Thank you, @EKtheSage!! |
|
I see that the other PR is not really a duplicate but cover more methods. We really should slim those down to make review easier. I'll reply on the other thread for issues related there. |
3 participants
Summary
Examplessections with.. testsetup::,.. testcode::, and.. testoutput::directives toBarnettZehnwirth,ClarkLDF,IncrementalAdditive,TweedieGLM, andDevelopmentMLgroupby,formula,power/link,fit_incrementals)MackChainladderclass-level andfull_std_err_docstrings to use correct::directives so Sphinx doctests execute them correctlyTest plan
.. testoutput::blocks match actual estimator outputMackChainladderdoctests pass end-to-endNote
Low Risk
Changes are limited to documentation/doctest blocks and a new GitHub Actions workflow; no runtime logic is modified, but the new workflow can introduce merge conflicts or unexpected pushes to the docs branch if misconfigured.
Overview
Adds new
Examplessections with.. testsetup::/.. testcode::/.. testoutput::doctest blocks toBarnettZehnwirth,ClarkLDF,TweedieGLM,IncrementalAdditive, andDevelopmentML, demonstrating how key parameters change fitted outputs.Fixes
MackChainladderdocstrings to use doctest-compatible directive syntax and expands examples (including a case showing how pre-smoothing affectstotal_mack_std_err_).Introduces a GitHub Actions workflow (
sync-main-to-docs.yml) that, on every push tomain, checks outdocs/great-docs-prototype, mergesorigin/main, and pushes the result back to that branch.Reviewed by Cursor Bugbot for commit 1df94ec. Bugbot is set up for automated code reviews on this repo. Configure here.