Skip to content

Pin the cross-document explicit-target reference from #1151 - #1198

Open
dchaudhari7177 wants to merge 1 commit into
executablebooks:masterfrom
dchaudhari7177:fix/1151-false-positive-xref-missing
Open

Pin the cross-document explicit-target reference from #1151#1198
dchaudhari7177 wants to merge 1 commit into
executablebooks:masterfrom
dchaudhari7177:fix/1151-false-positive-xref-missing

Conversation

@dchaudhari7177

Copy link
Copy Markdown

Closes #1151already fixed on master, so this is the regression test only.

The bisect

I ran the issue's reproduction verbatim against both:

v5.1.0   WARNING: local id not found in doc 'a': 'custom-anchor' [myst.xref_missing]
master   (no warning)

#1158 (stable heading anchors … explicit-id priority) landed after v5.1.0, which is the release the reporter was on. So the fix is in, and the issue can be closed once this or something like it guards it.

Why a new test rather than relying on doc_with_target_id

doc_with_target_id ("(ref)=\n# Title\n[](index.md#ref)") looks like it covers this, but it differs from the reported case in the two ways that mattered:

  • It is one file. The target and the link are both in index.md; the issue is about a link in b.md to a target in a.md.
  • It does not enable myst_heading_anchors. The false positive came from heading-anchor resolution taking precedence over the explicit target, so a case without heading anchors cannot see it.

The new test uses two documents with myst_heading_anchors: 3, and puts the explicit target directly above a heading — the placement that made heading-anchor resolution take over. It asserts on both spellings together ([](a.md#custom-anchor) and [](#custom-anchor)), since the bug was precisely that the two disagreed.

sphinx_doctree.srcdir is used to write the second file before the call, which is the only wrinkle — the fixture's __call__ writes one file, but the source directory is available for the rest.

Verified the test bites

Checked out v5.1.0, copied this test in, and ran it:

E  assert not "<src>\index.md:3: WARNING: local id not found in doc 'a': 'custom-anchor' [myst.xref_missing]"
FAILED test_cross_document_reference_to_an_explicit_target

Exactly the warning from the issue. On master it passes.

pytest tests/test_renderers/test_myst_refs.py    14 passed, 2 skipped
ruff 0.15.20 check / format                      clean

No source change, so no changelog entry.

…#1151

`[](a.md#custom-anchor)` emitted

    local id not found in doc 'a': 'custom-anchor' [myst.xref_missing]

on 5.1.0, while rendering the correct working href -- and the pathless
`[](#custom-anchor)` form of the same reference resolved silently.

This is already fixed on master: executablebooks#1158 (explicit-id priority) landed after
v5.1.0. Bisected by running the issue's reproduction against both:

    v5.1.0   WARNING: local id not found in doc 'a': 'custom-anchor'
    master   (no warning)

So this adds only the regression test. The existing `doc_with_target_id`
case looks like it covers this, but it has the target and the link in one
file and does not enable `myst_heading_anchors` -- and it is the combination
of a second document plus heading-anchor resolution that produced the false
positive. The target is placed directly above a heading for the same reason.

Verified the test bites: on v5.1.0 it fails with exactly the warning from
the issue.

Closes executablebooks#1151
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.

Cross-reference to an explicit target emits a false-positive myst.xref_missing warning

1 participant