POC: use sphinx-linkcode extension - #7268
Conversation
There was a problem hiding this comment.
Templating
This PR includes changes that may be worth sharing via templating. For each file listed below, please either:
- Action the suggestion via a pull request editing/adding the relevant file in the SciTools/.github
templates/directory. 1 - Raise an issue against the SciTools/.github repo for the above action if you really don't have 10mins spare right now. Include an assignee, to avoid it being forgotten.
- Dismiss the suggestion if the changes are not suitable for templating.
You will need to dismiss this review before this PR can be merged. Recommend the reviewer does this as their final action before merging, as this text will continually update as commits come in.
Template candidates
The following changed files are not currently templated, but their parent directories suggest they may be good candidates for a new template to be created:
Footnotes
-
Include this text in the PR body to avoid any notifications about applying the template changes back to the source repo!
@scitools-templating: please no update notification on: iris↩
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #7268 +/- ##
=======================================
Coverage 90.42% 90.42%
=======================================
Files 93 93
Lines 25816 25816
Branches 4796 4796
=======================================
Hits 23344 23344
Misses 1693 1693
Partials 779 779 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
stephenworsley
left a comment
There was a problem hiding this comment.
Nice work! I think this could be a cool addition.
Looks like there's a couple of cases would need special handling:
- Objects defined in an
__init__.pyfile, e.g. https://scitools-iris--7268.org.readthedocs.build/en/7268/generated/api/iris.analysis.html#iris.analysis.Aggregator. - Objects defined in a private module and imported into a public one, e.g. https://scitools-iris--7268.org.readthedocs.build/en/7268/generated/api/iris.analysis.cartography.html#iris.analysis.cartography.gridcell_angles .
In terms of putting this somewhere central, I believe the way we currently work is that we have the code elsewhere for GitHub workflows (https://github.com/SciTools/workflows/tree/main/.github/workflows), but for most config stuff we tend to centralise this with templating, as the CI comment above has indicated.
Description
Some other packages I often use (Matplotlib, Numpy, Scipy) use the sphinx-linkcode extension to point the
[source]links in the API docs to the relevant code in GitHub. I find this really useful because, once I'm studying the object's code in GitHub, it's easy to navigate to other internal code that it depends on.I'm opening this as a proof-of-concept for how it could work in Iris, but I wonder if it would be better to put the
linkcode_resolvefunction somewhere central that multiple Scitools projects could import from. I adapted the function from Matplotlib's version.Checklist
Important
The Iris core developers are here to help! If anything below is unclear, just post a comment asking for help 😊
(further reading)
Tip
Things you can trigger on this PR:
9999for this PR's number - to re-trigger the CLA check:https://cla-assistant.io/check/SciTools/iris?pullRequest=9999