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.
A
{ref}to a solution renders the correct title from the same document but a truncated one from any other document. Reproduced onmain(f721c3f) with Sphinx 8.2.3.Reproduction
chapter1.mddefines an exerciseex-1and a solutionsol-1, and references the solution.other.mdreferences the same solution.{ref}tosol-1fromchapter1Solution to Exercise 1 (Some exercise)✅{ref}tosol-1fromotherSolution to❌{ref}toex-1fromotherExercise 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_readregisters the label withsection_name = node.attributes.get("title"). Atdoctree-readtime a solution node'stitleis 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 theResolveTitlesInSolutionspost-transform. So the std domain permanently stores("chapter1", "sol-1", "Solution to").2. The repair only reaches same-document references.
ResolveLinkTextToSolutionsfixes up reference text, but it matches onnode.get("refid"):refid = node.get("refid")/if refid in self.env.sphinx_exercise_registry:Same-document references carry
refid. Cross-document references carryrefuriinstead, never enter that branch, and keep the read-time title the std domain handed them.Exercises escape this because enumerated exercise references go through
UpdateReferencesToEnumeratedand are resolved asnumref, which derives its text from the figure-number machinery rather than the stored label title.Suggested fix
Either handle
refuri-style references inResolveLinkTextToSolutionsas well asrefidones, 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.