Fix workflow warning by salexanian · Pull Request #1120 · casact/chainladder-python

salexanian · 2026-07-14T19:13:59Z

Summary of Changes

This PR fixes a number of documentation build warnings, including:

-broken internal references in the installation and workflow documentation,
-ambiguous MyST cross-references in the user guide,
-missing intersphinx configuration for scikit-learn references,
-several API/docstring cross-reference issues.

This branch is based on #1091 as discussed. Once #1091 is merged, I'll update this branch against the latest main so the PR contains only these changes.

Issue 1:

/home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/getting_started/install.md:27: WARNING: 'myst' cross-reference target not found: 'contributing' [myst.xref_missing]

Improper relative path. Fixed by changing please refer to [Contributing](contributing) in line 27 of install.md to please refer to [Contributing](../library/contributing).

Issue 2: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/envs/main/lib/python3.11/site-packages/chainladder/workflow/gridsearch.py:docstring of chainladder.workflow.gridsearch.GridSearch:39: WARNING: term not in glossary: 'n_jobs'

This problem was due to two issues - n_jobs was missing from the glossary.md file, and the lack of the Sphinx 'glossary' directive in glossary.md. I rectified this by: 1) adding the glossary directive to the glossary.md file and 2) amending the docstring for n_jobs by reducing it to the first descriptive sentence in the docstring, and then moving the more detailed remainder of the docstring to the glossary.md file in a new n_jobs entry.

Issue 3: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/envs/main/lib/python3.11/site-packages/chainladder/workflow/gridsearch.py:docstring of chainladder.workflow.gridsearch.Pipeline:4: WARNING: undefined label: 'pipeline_docs'

This error was due to a broken reference. After finding the proper reference in the code, I modified line 164 of gridsearch.py to read Read more in the :ref:User Guide <workflow:pipeline>

Issue 4: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/envs/main/lib/python3.11/site-packages/chainladder/workflow/gridsearch.py:docstring of chainladder.workflow.gridsearch.Pipeline.fit:32: WARNING: undefined label: 'metadata_routing'

This error was due to an inability for the docstring to import the metadata_routing label from the sklearn library due to a failure to load intersphinx properly. I fixed this by adding new line 40 to _config.yml as follows - sphinx.ext.intersphinx and by adding the new lines 50-53 as follows to the same file:

      sklearn:
        - https://scikit-learn.org/stable/
        - null

Issue 5 and 6: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/envs/main/lib/python3.11/site-packages/chainladder/workflow/gridsearch.py:docstring of chainladder.workflow.gridsearch.Pipeline.fit_predict:34: WARNING: undefined label: 'metadata_routing' /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/envs/main/lib/python3.11/site-packages/chainladder/workflow/gridsearch.py:docstring of chainladder.workflow.gridsearch.Pipeline.predict:30: WARNING: undefined label: 'metadata_routing'

Solved by the solution to Issue 4 above.

Issue 7: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/envs/main/lib/python3.11/site-packages/chainladder/workflow/voting.py:docstring of chainladder.workflow.voting.VotingChainladder:9: WARNING: undefined label: 'voting'

Fixed by amending line 165 of voting.py to read: Read more in the :ref:User Guide <workflow:votingchainladder>. (the reference within the chevrons was wrong).

Issue 8: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/development.ipynb:540023: WARNING: 'myst' cross-reference target not found: 'modules/generated/chainladder.MunichAdjustment' [myst.xref_missing]

Fixed by correcting path from modules/generated/chainladder.MunichAdjustment to ../library/generated/chainladder.MunichAdjustment in development.ipynb. Also fixed reference to BerquistSherman to add a link like for Munich (housekeeping change).

Issues 9-11: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/development.ipynb:540026: WARNING: 'myst' cross-reference target not found: 'modules/generated/chainladder.MunichAdjustment' [myst.xref_missing] /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/development.ipynb:540030: WARNING: 'myst' cross-reference target not found: 'modules/generated/chainladder.MunichAdjustment' [myst.xref_missing] /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/development.ipynb:620011: WARNING: 'myst' cross-reference target not found: 'modules/generated/chainladder.MunichAdjustment' [myst.xref_missing]

Solved by solution to issue 8 above.

Issues 12 and 13: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/index.md:12: WARNING: more than one target found for 'myst' cross-reference triangle: could be :std:ref:Triangles or :std:doc:Triangles [myst.xref_ambiguous] /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/index.md:22: WARNING: more than one target found for 'myst' cross-reference triangle: could be :std:ref:Triangle or :std:doc:Triangle [myst.xref_ambiguous]

Changed [Triangle](triangle) to {doc}Triangles for the first reference, and changedClasses: TriangletoClasses: {py:class}chainladder.Triangle`.

Issue 14: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/index.md:29: WARNING: more than one target found for 'myst' cross-reference development: could be :std:doc:Development or :py:mod:chainladder.development [myst.xref_ambiguous]

Similar change to issues 12 and 13 above.

Issues 15-19: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/index.md:45: WARNING: more than one target found for 'myst' cross-reference tails: could be :std:doc:Tail Estimation or :py:mod:chainladder.tails [myst.xref_ambiguous] /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/index.md:61: WARNING: more than one target found for 'myst' cross-reference methods: could be :std:doc:IBNR Models or :py:mod:chainladder.methods [myst.xref_ambiguous] /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/index.md:79: WARNING: more than one target found for 'myst' cross-reference adjustments: could be :std:doc:Adjustments or :py:mod:chainladder.adjustments [myst.xref_ambiguous] /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/checkouts/main/docs/user_guide/index.md:97: WARNING: more than one target found for 'myst' cross-reference workflow: could be :std:doc:Workflow or :py:mod:chainladder.workflow [myst.xref_ambiguous]

Similar changes to issues 12 and 13 above.

Issue 20: I also fixed the following issue: /home/docs/checkouts/readthedocs.org/user_builds/chainladder-python/envs/main/lib/python3.11/site-packages/chainladder/core/triangle.py:docstring of chainladder.core.triangle.Triangle:97: ERROR: Unknown target name: "ultimate". looking for now-outdated files... none found

by changing a reference to ultimate_ to 'ultimate_'

The warnings no longer show when I perform the build using uv run jb build ..

Related GitHub Issue(s)

#1091 and #1111

Additional Context for Reviewers

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
Documentation and docstring-only changes with no application logic or API behavior changes.

Overview
This PR targets Sphinx/Jupyter Book build warnings rather than runtime behavior.

Docstrings in gridsearch.py and voting.py now point at the correct user-guide labels (workflow:pipeline, workflow:votingchainladder). GridSearch’s n_jobs parameter defers detail to the glossary via :term:Glossary <n_jobs>. **`Triangle`** disposal-rate docs use double-backtick ultimate_`` so Sphinx does not treat it as a broken link target.

Sphinx config adds sphinx.ext.intersphinx and a scikit-learn mapping in _config.yml / conf.py so sklearn docstring references (e.g. metadata_routing) resolve. numpydoc_show_class_members is set consistently in generated conf.py.

User-facing docs: the install page’s Contributing link uses ../library/contributing; the user guide index replaces ambiguous MyST links with explicit {doc} / {py:class} roles; development.ipynb fixes generated API paths and adds a BerquistSherman link. glossary.md wraps terms in {glossary} directives, adds an n_jobs entry, and fixes the package name typo chanladder → chainladder.

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

github-actions · 2026-07-14T19:14:49Z

Pyright Type Completeness

View the full pyright --verifytypes output for this commit

Project (full chainladder package, at this PR's head): 14.9% of exported symbols fully typed (191 / 1281)

	Known	Ambiguous	Unknown	Total
Project (head)	191	110	980	1281

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: 312
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 · 2026-07-14T19:20:00Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.81%. Comparing base (4533ef6) to head (f2f5f89).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1120   +/-   ##
=======================================
  Coverage   90.81%   90.81%           
=======================================
  Files          91       91           
  Lines        5300     5300           
  Branches      673      673           
=======================================
  Hits         4813     4813           
  Misses        346      346           
  Partials      141      141

Flag	Coverage Δ
unittests	`90.81% <ø> (ø)`

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 · 2026-07-14T22:57:10Z

#1091 is merged to main

henrydingliu · 2026-07-15T07:50:32Z

@salexanian i just realized that the only place to test these fixes on our repo is directly on RTD. so i cleared out experimental. could you please merge in the latest main, then redirect this PR to experimental?

cursor

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.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 4ba1002. Configure here.}

salexanian · 2026-07-15T10:29:34Z

@salexanian i just realized that the only place to test these fixes on our repo is directly on RTD. so i cleared out experimental. could you please merge in the latest main, then redirect this PR to experimental?

@henrydingliu , no problem. Per your suggestion, I've merged the latest main into this branch and retargeted the PR to experimental for RTD validation.

henrydingliu · 2026-07-15T15:48:02Z

 +++

-**Algorithms**: [Development](development:development), [ClarkLDF](development:clarkldf), …
+**Algorithms**: {py:class}`chainladder.Development`,


this is now pointing to the API. the itnent is to point it to a dedication section in the user guide pages.

Fix documentation build warnings and cross-references

15de926

salexanian requested review from genedan, henrydingliu, jbogaardt and kennethshsu as code owners July 14, 2026 19:14

Merge remote-tracking branch 'upstream/main' into fix-workflow-warning

4ba1002

cursor Bot reviewed Jul 15, 2026

View reviewed changes

Comment thread docs/conf.py

Restore local Sphinx extension path

f2f5f89

henrydingliu reviewed Jul 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix workflow warning#1120

Fix workflow warning#1120
salexanian wants to merge 3 commits into
casact:mainfrom
salexanian:fix-workflow-warning

salexanian commented Jul 14, 2026 •

edited by cursor Bot

Loading

Uh oh!

github-actions Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

henrydingliu commented Jul 14, 2026

Uh oh!

henrydingliu commented Jul 15, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

salexanian commented Jul 15, 2026

Uh oh!

henrydingliu Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

salexanian commented Jul 14, 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!

github-actions Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pyright Type Completeness

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

henrydingliu commented Jul 14, 2026

Uh oh!

henrydingliu commented Jul 15, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

salexanian commented Jul 15, 2026

Uh oh!

henrydingliu Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

salexanian commented Jul 14, 2026 •

edited by cursor Bot

Loading

github-actions Bot commented Jul 14, 2026 •

edited

Loading

codecov Bot commented Jul 14, 2026 •

edited

Loading