Skip to content

Cross-document {ref} to a solution renders truncated link text #91

Description

@mmcky

A {ref} to a solution renders the correct title from the same document but a truncated one from any other document. Reproduced on main (f721c3f) with Sphinx 8.2.3.

Reproduction

chapter1.md defines an exercise ex-1 and a solution sol-1, and references the solution. other.md references the same solution.

Reference Renders as
{ref} to sol-1 from chapter1 Solution to Exercise 1 (Some exercise)
{ref} to sol-1 from other Solution to
{ref} to ex-1 from other Exercise 1 ✅ (exercises are unaffected)

The link target is correct in every case — only the link text is wrong, and only for solutions referenced across documents. The build reports no warning.

Root cause

Two mechanisms resolve solution link text, and only one of them covers cross-document references.

1. The std-domain label title is captured too early. doctree_read registers the label with section_name = node.attributes.get("title"). At doctree-read time a solution node's title is still the unresolved default set by the directive — literally the string "Solution to". The full title, with the exercise number and subtitle, is not built until the ResolveTitlesInSolutions post-transform. So the std domain permanently stores ("chapter1", "sol-1", "Solution to").

2. The repair only reaches same-document references. ResolveLinkTextToSolutions fixes up reference text, but it matches on node.get("refid"):

refid = node.get("refid") / if refid in self.env.sphinx_exercise_registry:

Same-document references carry refid. Cross-document references carry refuri instead, never enter that branch, and keep the read-time title the std domain handed them.

Exercises escape this because enumerated exercise references go through UpdateReferencesToEnumerated and are resolved as numref, which derives its text from the figure-number machinery rather than the stored label title.

Suggested fix

Either handle refuri-style references in ResolveLinkTextToSolutions as well as refid ones, or update the std-domain label title once the real title is known rather than storing the placeholder at read time. The second is cleaner but has to happen somewhere the domain data is still writable and before references resolve.

Worth a regression test with a solution referenced from a second document — the existing _linked_ref_* fixtures are all same-document, which is why this is not caught today.

Context

Found while researching #87. The solution-relocation work proposed there would inherit and amplify this, since relocating a solution makes every reference to it effectively cross-document.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions