Skip to content

DM-55634: Backport the Edit on GitHub source-directory fix to 2.4 - #355

Merged
jonathansick merged 1 commit into
2.4from
tickets/DM-55634-2.4
Jul 27, 2026
Merged

DM-55634: Backport the Edit on GitHub source-directory fix to 2.4#355
jonathansick merged 1 commit into
2.4from
tickets/DM-55634-2.4

Conversation

@jonathansick

Copy link
Copy Markdown
Member

Summary

Backport of #352 onto the new 2.4 release branch, for a 2.4.x patch release.

  • The "Edit on GitHub" button now resolves its in-repository path from the Sphinx source directory rather than the directory holding conf.py. Projects that build with sphinx-build -c . docs _build/html (where those differ) no longer emit links that 404 — this is what https://dp2.lsst.io/ hits today. A source directory at the repository root also no longer produces a stray ./.
  • The path is computed by a new documenteer.ext.githubeditlink extension at config-inited, the earliest event where srcdir is known. An explicitly configured html_context["doc_path"] is honored and short-circuits auto-detection.
  • Building outside a Git checkout no longer raises InvalidGitRepositoryError at configuration time; the button is omitted instead.

Backport adaptations

The 2.4 branch predates several things the original PR touched, so this is not a clean replay:

  • _toml.py drops its ._utils import entirely rather than narrowing it — normalize_origin_base_url and the storage clients don't exist on 2.4.
  • The test-guide and test-linkcheck-service* roots don't exist yet, so only test-redoc is relaxed (and gains a github_url, since show_github_edit_link now defaults on).
  • tests/test_conf_toml.py takes only the three set_edit_on_github guard tests; the link-check service cases belong to a later feature.
  • tests/ext/conftest.py is brought along, because tests/roots/test-redoc also builds the guide preset — without the module-eviction fixture, the two guide-stack builds in one pytest process would share cached settings.

Validation steps

Run against this branch's own tooling (2.4 uses tox, not nox):

tox -e py-test-sphinx8    # 84 passed
tox -e typing-sphinx8     # clean
tox -e lint               # clean
tox -e docs               # builds, including the new extension page

All four pass locally. The suite includes the wiring test that drives the real guide preset in the -c ./docs layout, which was confirmed on main to fail if the extension is unregistered.

References

Cherry-picks PR #352 onto the 2.4 release branch. The button now
resolves its in-repository path from the Sphinx source directory rather
than the directory holding conf.py, so projects building with
'sphinx-build -c . docs ...' no longer emit 404 links, and a source
directory at the repository root no longer yields a stray './'.

Adapted for 2.4, which predates several things the original touched:

- _toml.py drops the ._utils import entirely rather than narrowing it;
  normalize_origin_base_url and the storage clients don't exist here.
- The test-guide and test-linkcheck-service* roots don't exist yet, so
  only test-redoc is relaxed.
- test_conf_toml.py takes only the three set_edit_on_github guard tests;
  the link-check service cases belong to a later feature.
- tests/ext/conftest.py comes along because tests/roots/test-redoc also
  builds the guide preset, and without the module-eviction fixture the
  two guide-stack builds would share cached settings.

Verified on this branch with tox: py-test-sphinx8 (84 passed),
typing-sphinx8, lint, and docs all pass.
@jonathansick
jonathansick merged commit 5382a39 into 2.4 Jul 27, 2026
8 checks passed
@jonathansick
jonathansick deleted the tickets/DM-55634-2.4 branch July 27, 2026 20:13
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