Fix the broken API source links, and mark and cross-link the documentation trees - #878
Merged
Conversation
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
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.
Every
[source]link in the API documentation was a 404.doc/conf.pypassed_version_dict["git_branch"]toLinkCodeResolver, but that value is always empty:_version_info()is called with the defaultsections="", andversion.pyonly queriesthe branch when
sectionsis non-empty. So the links were built ashttps://github.com/Deep-MI/FastSurfer/blob//CerebNet/apply_warp.py#L29-L53, note thedouble slash, which GitHub answers with 404. Confirmed live on both published trees.
They now use the commit hash, which is populated, always resolves, and unlike a branch
keeps the line numbers matching the code that was documented.
resolve_links.pyrejectsan empty ref instead of silently producing
blob//, and joins the path with exactly oneslash.
DOC_URLpointed at a page that does not exist. The OCI label baked into everypublished image was
https://fastsurfer.org/fastsurfer/dev, a 404, andtools/Docker/build.pyusedhttps://deep-mi.org/fastsurfer/stable, also a 404 becausethe path is case sensitive. Both now point at
https://deep-mi.org/FastSurfer/..., as theissue templates already did.
pyproject.toml'sdocumentationURL pointed at the researchlanding page rather than the documentation.
The two published trees are now marked and cross-linked. A bar above the page content
says whether you are reading a release or the development version, and links to the other
tree. The condition uses
GITHUB_REF_NAME, the same valuedoc.ymluses fordestination_dir, so the banner and the publish location cannot disagree.doc/_static/doc-version-link.jsresolves the sibling tree fromrel="index"rather thanfrom a hardcoded path, because the bar is one string shared by every page and a relative
path would break on nested ones.
Verified by building with
-WT --keep-goingfor bothdevandstable, checking thegenerated links from a nested page, and confirming the new link shape returns 200 against a
pushed commit.