Skip to content

Fix the broken API source links, and mark and cross-link the documentation trees - #878

Merged
m-reuter merged 5 commits into
Deep-MI:devfrom
m-reuter:doc
Sep 11, 2026
Merged

Fix the broken API source links, and mark and cross-link the documentation trees#878
m-reuter merged 5 commits into
Deep-MI:devfrom
m-reuter:doc

Conversation

@m-reuter

Copy link
Copy Markdown
Member

Every [source] link in the API documentation was a 404. doc/conf.py passed
_version_dict["git_branch"] to LinkCodeResolver, but that value is always empty:
_version_info() is called with the default sections="", and version.py only queries
the branch when sections is non-empty. So the links were built as
https://github.com/Deep-MI/FastSurfer/blob//CerebNet/apply_warp.py#L29-L53, note the
double 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.py rejects
an empty ref instead of silently producing blob//, and joins the path with exactly one
slash.

DOC_URL pointed at a page that does not exist. The OCI label baked into every
published image was https://fastsurfer.org/fastsurfer/dev, a 404, and
tools/Docker/build.py used https://deep-mi.org/fastsurfer/stable, also a 404 because
the path is case sensitive. Both now point at https://deep-mi.org/FastSurfer/..., as the
issue templates already did. pyproject.toml's documentation URL pointed at the research
landing 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 value doc.yml uses for
destination_dir, so the banner and the publish location cannot disagree.
doc/_static/doc-version-link.js resolves the sibling tree from rel="index" rather than
from 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-going for both dev and stable, checking the
generated links from a nested page, and confirming the new link shape returns 200 against a
pushed commit.

@m-reuter
m-reuter merged commit 52e7dfa into Deep-MI:dev Sep 11, 2026
5 checks passed
@m-reuter
m-reuter deleted the doc branch September 11, 2026 13:38
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.

1 participant