docs: make SKIP_URL_CHECK=1 actually bypass the gh-file-ref URL checks - #2367
Open
eastagiletracker wants to merge 1 commit into
Open
docs: make SKIP_URL_CHECK=1 actually bypass the gh-file-ref URL checks#2367eastagiletracker wants to merge 1 commit into
eastagiletracker wants to merge 1 commit into
Conversation
The :gh-file-ref: role consulted SKIP_URL_CHECK only inside the ConnectionError branch, so a live requests.get() to github.com was still issued for every reference and a non-200 response or a read timeout aborted the whole build via sys.exit(1) even when the flag was set. This defeats the documented purpose of the variable (offline and local builds such as the Starlight sync, which sets it) and makes those builds depend on the network. Guard the entire verification on SKIP_URL_CHECK so the flag bypasses the check as documented. When it is unset the behavior is unchanged, so the dead-link validation run by `make -C docs html` in CI is preserved.
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
1 participant
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.
This PR proposes making the documentation build's
SKIP_URL_CHECK=1escape hatch actually skip the external github.com link checks, so local and offline docs builds no longer depend on network access. We include this PR work along with a full history of your repo at https://eastagiletracker.com/projects/240. You can sign in with your GitHub ID to claim ownership of the project.What this changes
docs/conf.pydefines the:gh-file-ref:role, which verifies every referenced repo path by issuing a liverequests.get()togithub.comwhile Sphinx builds the docs.SKIP_URL_CHECK=1is documented as the way to turn those checks off for offline and local work:docs/README.mdsays it "lets the build continue if the custom external URL checks cannot access the network," the role prints "set the SKIP_URL_CHECK=1 environment variable to bypass URL checks," anddocs/scripts/sphinx_to_starlight.pysets it (env.setdefault("SKIP_URL_CHECK", "1")) so the Starlight sync does not need the network.The problem is that the flag is only consulted inside the
ConnectionErrorbranch. Therequests.get()call is still made for every reference regardless of the flag, and a non-200 response or a read timeout still aborts the whole build viasys.exit(1)even whenSKIP_URL_CHECK=1is set. So the documented escape hatch does not actually bypass the checks:npm run build/npm run dev/ the Sphinx preview still reach out to github.com once per reference and remain fragile to anything other than a clean connection failure.Reproduction at current
mainFrom
docs/, run the Starlight-sync Sphinx build with the flag set:At
e27c656this still printsTesting GitHub URL https://github.com/... exists...and makes a network request for each of the:gh-file-ref:references (16 in the sources; 13 in the built pages). In a network-restricted run one of those requests timed out againstgithub.com— exactly the situation the flag is supposed to make safe.The fix
Guard the entire verification block behind
if os.environ.get("SKIP_URL_CHECK") != "1":so the flag skips the network access completely, and drop the now-unreachable innerSKIP_URL_CHECKconditional in theConnectionErrorhandler. When the flag is unset the behavior is byte-for-byte unchanged, so the dead-link validation your CI relies on (make -C docs html, which does not set the flag) still runs and still fails on a genuinely missing path.Verification
With the change, the same command above makes zero requests to github.com and completes without touching the network, while an unset flag still performs the check and still exits non-zero on a dead link. I confirmed both directions with a focused check that drives the role directly: with
SKIP_URL_CHECK=1it returns the reference node without callingrequests.get, and with the flag unset it performs the request. The Sphinx build was run before and after the change with no new failures (the flag-set build went from 13 network checks to zero; the flag-unset verification path is byte-for-byte unchanged).Backward compatibility
The change is opt-in and additive: only the
SKIP_URL_CHECK=1code path is affected, and only to match its already-documented contract. Builds that do not set the variable (including CI) keep validating links exactly as before.How this was managed
This work was tracked on a live board that mirrors this repository's history, imported from your own issues and pull requests (2,286 stories and 26 labels). The specific item for this change is at https://eastagiletracker.com/projects/240/stories/126308, and the full board is at https://eastagiletracker.com/projects/240.
If you'd rather not receive contributions like this, reply
no-more-prson this pull request and we won't open any further ones on your repositories.Lawrence W. Sinclair
CEO / East Agile
linkedin.com/in/lwsinclair/
eastagile.com