docs: link API entries to their source on GitHub - #1185
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1185 +/- ##
=======================================
Coverage 92.41% 92.41%
=======================================
Files 52 52
Lines 7874 7874
=======================================
Hits 7277 7277
Misses 597 597 🚀 New features to boost your workflow:
|
The API reference had no "[source]" links, because neither sphinx.ext.linkcode nor sphinx.ext.viewcode was enabled. Enable sphinx.ext.linkcode and let scanpydoc.rtd_github_links supply the linkcode_resolve implementation, which derives GitHub URLs from the html_context metadata already defined here. scanpydoc is used rather than a hand-written linkcode_resolve because a naive resolver has to import every documented module and bake a commit SHA into each URL, which defeats Sphinx's incremental caching. This is the same setup scanpy and anndata use. rtd_links_prefix is set to "src" for the src-layout, and a small git_ref extension (adapted from scanpy) resolves the current branch/tag so that released docs link to the code they document instead of always main.
jan-glx
force-pushed
the
docs/linkcode-github-links
branch
from
August 19, 2026 15:01
5a1cf64 to
4053db6
Compare
On pull request builds Read the Docs checks out a local branch named external-<pr>, which does not exist on GitHub, so every source link 404s. Use READTHEDOCS_GIT_COMMIT_HASH there instead; GitHub serves a pull request's head commit from the base repository, also for forks.
Collaborator
Author
|
52ce669 additionally adds an exception for PR doc builds so you can see it working live here: https://scverse-spatialdata--1185.org.readthedocs.build/en/1185/api/io.html |
jan-glx
marked this pull request as ready for review
August 19, 2026 15:47
LucaMarconato
approved these changes
Aug 20, 2026
LucaMarconato
left a comment
LucaMarconato
left a comment
Member
There was a problem hiding this comment.
Thanks! Tested on the readsthedocs deployment for this PR and works great.
Comment on lines
+39
to
+46
| # On Read the Docs pull request previews, HEAD is a local branch such as | ||
| # "external-1185" that does not exist on GitHub, so use the commit instead. | ||
| # GitHub serves a pull request's head commit from the base repository, also | ||
| # when the branch itself lives on a fork. | ||
| if os.environ.get("READTHEDOCS_VERSION_TYPE") == "external" and ( | ||
| commit := os.environ.get("READTHEDOCS_GIT_COMMIT_HASH") | ||
| ): | ||
| return commit |
Member
There was a problem hiding this comment.
Seems useful also for scanpy/scversedocs. CC-ing @flying-sheep
Collaborator
Author
There was a problem hiding this comment.
yes, potentially. But how often do you need to go to the PR source from a PR's docs build? More importantly, git_ref.py should move to scanpy/scversedocs.
Keeps the file byte-identical to scanpy's docs/extensions/git_ref.py so upstream changes can be ported without reconciling a local fork. This drops the html_context["github_version"] target and the Read the Docs pull-request handling, so the ref injection is currently a no-op for this project.
This reverts commit d2fcf34.
jan-glx
marked this pull request as draft
August 20, 2026 12:50
Restore the runtime ExtensionMetadata import and constructor, and the app.config access in set_ref, so the only remaining differences from scanpy's docs/extensions/git_ref.py are the docstring, the target config key, and the Read the Docs pull-request handling.
jan-glx
marked this pull request as ready for review
August 20, 2026 13:20
Collaborator
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
scanpy and anndata already link API entries to their source on GitHub, via
scanpydoc+sphinx.ext.linkcode. spatialdata enables neitherlinkcodenorviewcode, so its API reference has no[source]links at all, see, e.g.,api/io.html.This PR follows scanpy's approach:
sphinx.ext.linkcodeemits the linksscanpydoc.rtd_github_linksbuilds the URLs from thehtml_contextalready indocs/conf.py(See also discussion in cookiecutter-scverse#103)docs/extensions/git_ref.py, taken from scanpy, resolves the current tag so released docs link to their own code.Will need revisiting if theislab/scanpydoc#238 lands.