Skip to content

Add links to object source code in API Reference section#710

Merged
genedan merged 9 commits intocasact:mainfrom
genedan:gd_linkcode
Apr 23, 2026
Merged

Add links to object source code in API Reference section#710
genedan merged 9 commits intocasact:mainfrom
genedan:gd_linkcode

Conversation

@genedan
Copy link
Copy Markdown
Collaborator

@genedan genedan commented Apr 23, 2026

Closes #709. This PR includes:

  1. Specifies extension sphinx.ext.linkcode and local extension ext_linkcode. The local extension is required since we're using Jupyterbook, which seems to override many of the things in the usual Sphinx conf.py, so I had to write a custom extension.
  2. A function called linkcode_resolve that extracts the line numbers from an object and then creates the URL to the GitHub source code.
  3. Unit test for linkcode_resolve.

This is adapted from the Pandas' implementation:
https://github.com/pandas-dev/pandas/blob/ab90747e3dae0e69b1bdbf083820b8075689b34b/doc/source/conf.py#L646

I removed many of the error-handling blocks since at the moment, we just don't know what errors might occur and I don't want to include more than what we need. We can add them back if we encounter any problems.

Reviewing this might be a bit tricky since it's not part of the package API. My IDE debugger wasn't working properly so the way I tried to figure out what the function was doing was by feeding it the arguments

  domain = 'py',
  info = {'module': 'chainladder', 'fullname': 'Benktander'}

Which outputs:

https://github.com/casact/chainladder-python/blob/master/chainladder/methods/benktander.py#L8-L129


Note

Low Risk
Low risk: changes are isolated to documentation build tooling and pytest configuration, with no impact on the library runtime behavior. Main risk is broken doc builds if linkcode_resolve cannot locate sources in some environments.

Overview
Adds Sphinx linkcode support to the Jupyter Book docs so API reference items can link directly to their GitHub source lines.

This introduces a local Sphinx extension (docs/_ext/ext_linkcode.py) that implements linkcode_resolve by importing the target object, locating its source file/line range via inspect, and constructing a GitHub URL, plus a small unit test for the generated URL format. Pytest is configured in pyproject.toml to discover tests under docs/_ext.

Reviewed by Cursor Bugbot for commit 4db19e2. Bugbot is set up for automated code reviews on this repo. Configure here.

@genedan genedan requested a review from kennethshsu April 23, 2026 20:40
Comment thread docs/_ext/ext_linkcode.py
@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 23, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.12%. Comparing base (6cb4aab) to head (4db19e2).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #710   +/-   ##
=======================================
  Coverage   85.12%   85.12%           
=======================================
  Files          85       85           
  Lines        4909     4909           
  Branches      629      629           
=======================================
  Hits         4179     4179           
  Misses        521      521           
  Partials      209      209           
Flag Coverage Δ
unittests 85.12% <ø> (ø)

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.

Comment thread docs/_ext/ext_linkcode.py Outdated
Comment thread docs/_ext/ext_linkcode.py Outdated
Comment thread docs/_ext/scratch_ext.py Outdated
Copy link
Copy Markdown

@cursor cursor Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

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

Reviewed by Cursor Bugbot for commit d362fb9. Configure here.

Comment thread docs/_ext/ext_linkcode.py
@genedan
Copy link
Copy Markdown
Collaborator Author

genedan commented Apr 23, 2026

I guess now you'll see all the struggles I had trying to get bugbot to clear this one. Feel free to squash all the commits.

@kennethshsu
Copy link
Copy Markdown
Collaborator

hahaha you are doing great, it would've taken me muchhhh longerrrrr....

Let's hope everything shows up correctly on the doc site. :)

@genedan genedan merged commit 298366b into casact:main Apr 23, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add link to source code URL in API Reference

2 participants