From 6c1390bb31c7fe95a67e8641bbd08d951bd74e8c Mon Sep 17 00:00:00 2001
From: Philipp Wagner <phw@ibm.com>
Date: Mon, 22 Jun 2026 10:48:52 +0200
Subject: [PATCH] Add support for cross-document references

Implement :doc:/:ref:/:confval:/etc. cross-references in the Typst
builder, following the same approach as Sphinx's LaTeX builder: all
documents are merged into a single doctree, and Sphinx's standard
env.resolve_references() runs against that merged tree right after
merging. This lets Sphinx's own domains handle path normalization,
label lookup, title substitution, and intersphinx exactly as they do
for any other builder.

Builder.get_target_uri()/get_relative_uri() map a docname onto the
single merged Typst document, mirroring the LaTeX builder's
"%docname" convention. The writer's job is then only to translate the
refid/refuri that Sphinx resolves into a namespaced Typst label
(<docname:id>); the namespace keeps ids from colliding across
documents now that they all share one output file. A small
per-document "#metadata(none) <label>" anchor - the same trick HTML
uses for an extra empty anchor per additional id on an element -
gives whole-document :doc: references something to link to even when
the target document has no sections, and covers section/signature
ids beyond the first, since Typst only allows one label per element.

Includes test coverage for basic cross-references, :ref: to named
targets, relative paths (including bare relative paths resolved from
the referring document's directory), nested documents, and edge
cases such as documents without sections and confval-style targets.
---
 src/atsphinx/typst/builders.py                |  28 +++-
 src/atsphinx/typst/writer.py                  |  99 ++++++++++++--
 tests/test_e2e/test_it.py                     | 128 ++++++++++++++++++
 tests/testdocs/test-cross-references/conf.py  |  14 ++
 .../testdocs/test-cross-references/index.rst  |  63 +++++++++
 .../test-cross-references/no_sections.rst     |   5 +
 .../testdocs/test-cross-references/page1.rst  |  16 +++
 .../testdocs/test-cross-references/page2.rst  |  23 ++++
 .../test-cross-references/subdir/nested.rst   |  26 ++++
 .../test-cross-references/subdir/sibling.rst  |   7 +
 10 files changed, 395 insertions(+), 14 deletions(-)
 create mode 100644 tests/testdocs/test-cross-references/conf.py
 create mode 100644 tests/testdocs/test-cross-references/index.rst
 create mode 100644 tests/testdocs/test-cross-references/no_sections.rst
 create mode 100644 tests/testdocs/test-cross-references/page1.rst
 create mode 100644 tests/testdocs/test-cross-references/page2.rst
 create mode 100644 tests/testdocs/test-cross-references/subdir/nested.rst
 create mode 100644 tests/testdocs/test-cross-references/subdir/sibling.rst

diff --git a/src/atsphinx/typst/builders.py b/src/atsphinx/typst/builders.py
index 53ff2ed..362cf92 100644
--- a/src/atsphinx/typst/builders.py
+++ b/src/atsphinx/typst/builders.py
@@ -12,7 +12,7 @@
 from sphinx import addnodes
 from sphinx._cli.util.colour import darkgreen
 from sphinx.builders import Builder
-from sphinx.errors import SphinxError
+from sphinx.errors import NoUri, SphinxError
 from sphinx.util.fileutil import copy_asset, copy_asset_file
 from sphinx.util.nodes import inline_all_toctrees
 
@@ -40,6 +40,10 @@ def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:  # noqa: D107
         self._static_dir = Path(self.outdir / "_static")
         self._images_dir = Path(self.outdir / "_images")
         self._build_date = date.today()
+        # Docnames merged into the document currently being written, like
+        # the LaTeX builder's ``self.docnames``. Populated by
+        # ``assemble_doctree()`` before it resolves references.
+        self.docnames: set[str] = set()
 
     def init(self):  # noqa: D102
         super().init()
@@ -111,13 +115,29 @@ def assemble_doctree(
                 root_section += toctree
             root = root.copy()
             root += root_section
-        tree = inline_all_toctrees(self, {docname}, docname, root, darkgreen, [docname])
+        self.docnames = {docname}
+        tree = inline_all_toctrees(
+            self, self.docnames, docname, root, darkgreen, [docname]
+        )
+        tree["docname"] = docname
+        # Like the LaTeX builder, resolve references right after merging so
+        # that Sphinx's own domains (:doc:, :ref:, :confval:, intersphinx,
+        # ...) do the resolution; see get_target_uri()/get_relative_uri()
+        # for how that maps onto the single merged Typst document.
         self.env.resolve_references(tree, docname, self)
         return tree
 
     def get_target_uri(self, docname, typ=None):  # noqa: D102
-        # TODO: Implement it!
-        return ""
+        if docname not in self.docnames:
+            raise NoUri(docname, typ)
+        # All documents are merged into one, so the docname itself is
+        # enough; the writer turns it into the appropriate Typst label.
+        return docname
+
+    def get_relative_uri(self, from_, to, typ=None):  # noqa: D102
+        # Ignore source path: there's only one output file, so there is no
+        # relative path to compute (cf. the LaTeX builder).
+        return self.get_target_uri(to, typ)
 
     def copy_assets(self):  # noqa: D102
         # Copying all theme assets.
diff --git a/src/atsphinx/typst/writer.py b/src/atsphinx/typst/writer.py
index 624093a..d41c346 100644
--- a/src/atsphinx/typst/writer.py
+++ b/src/atsphinx/typst/writer.py
@@ -38,6 +38,13 @@ def _typst_local_package_fullname(name: str, version: str | None = None) -> str:
     return f"@local/{name}:{version}"
 
 
+def _doc_label(docname: str) -> str:
+    # All documents are merged into a single Typst file, so every label
+    # needs a per-document namespace to avoid collisions between e.g. two
+    # documents that each have a "Installation" section.
+    return docname.replace("/", ":")
+
+
 class TypstTranslator(SphinxTranslator, BaseTypstTranslator):
     """Custom translator that has converter from dotctree to Typst syntax."""
 
@@ -65,15 +72,49 @@ def __init__(self, document: nodes.document, builder: Builder) -> None:
         self.context = {
             "has_index": False,
         }
+        # Track current document for cross-references (like the LaTeX
+        # writer's ``curfilestack``). The builder merges everything into
+        # one doctree, so this is what lets us namespace labels per
+        # document and tell which document a relative reference is in.
+        self.curfilestack = [document["docname"]]
 
     # ------
     # visit/departuer methods
     # ------
+    def visit_document(self, node: nodes.document):
+        super().visit_document(node)
+        self._write_anchor(_doc_label(self.curfilestack[-1]))
+
     def visit_title(self, node: nodes.title):
         if isinstance(node.parent, nodes.section) and self._section_level < 1:
             raise nodes.SkipNode
+
         super().visit_title(node)
 
+    def depart_title(self, node: nodes.title):
+        """Add a label to section titles for cross-referencing."""
+        docname = _doc_label(self.curfilestack[-1])
+        if isinstance(node.parent, nodes.section):
+            ids = node.parent.get("ids", [])
+        else:
+            ids = []
+
+        if ids:
+            # Add the section label AFTER the title text but BEFORE
+            # newlines. Typst syntax: == Title <label>
+            self.body.append(f" <{docname}:{ids[0]}>")
+
+        super().depart_title(node)
+
+        # Sphinx may register more than one id for a section (e.g. an
+        # explicit ``.. _target:`` placed right above the heading, used by
+        # :ref:). Typst only allows a single label per element, so the
+        # first id is attached directly to the heading above and every
+        # other id gets its own invisible anchor here - the same way HTML
+        # emits an empty anchor element for each extra id on a section.
+        for node_id in ids[1:]:
+            self._write_anchor(f"{docname}:{node_id}")
+
     # TODO: It should separate transform and translate.
     def visit_container(self, node: nodes.container):
         if node.get("literal_block"):
@@ -99,20 +140,40 @@ def visit_image(self, node: nodes.image):
         node["uri"] = uri_map
         super().visit_image(node)
 
-    def visit_reference(self, node):
+    def visit_reference(self, node: nodes.reference):
         # NOTE: It may be should implement in rst2typst.
         if not node.get("internal", False):
             return super().visit_reference(node)
-        if "refuri" in node:
-            uri = node["refuri"][1:]
-        elif "refid" in node:
-            uri = node["refid"]
+        if "refid" in node:
+            # Reference resolved within the current document (see
+            # ``curfilestack``), e.g. a ``:ref:`` to a label in this file.
+            uri = f"{_doc_label(self.curfilestack[-1])}:{node['refid']}"
+        elif "refuri" in node:
+            # Reference resolved to another document by Sphinx's standard
+            # reference resolution (``Builder.get_relative_uri``), shaped
+            # like ``docname`` or ``docname#labelid``.
+            docname, _, labelid = node["refuri"].partition("#")
+            uri = _doc_label(docname)
+            if labelid:
+                uri += f":{labelid}"
         else:
             raise ExtensionError("<reference> requires 'refuri' or 'refid' attribute")
         return self.body.append(f"#link(<{uri}>)[")
 
     # Implements for Sphinx's nodes
     # =============================
+    def visit_pending_xref(self, node: addnodes.pending_xref):
+        # NOTE: Implement this if rendering anything is needed.
+        #   By the time the writer runs, ``resolve_references()`` has
+        #   already replaced every resolvable ``pending_xref`` with a
+        #   plain ``reference`` node (see ``assemble_doctree``); like in
+        #   Sphinx's LaTeX writer, this is only reached for the rare case
+        #   of an unresolved reference left in place.
+        pass
+
+    def depart_pending_xref(self, node: addnodes.pending_xref):
+        pass
+
     def visit_desc(self, node: addnodes.desc):
         self.packages.add(_typst_local_package_fullname("atsphinx-typst"), "desc")
         self.body.append(f"{self._hi.prefix}#desc(\n")
@@ -127,10 +188,17 @@ def visit_desc_signature(self, node: addnodes.desc_signature):
         self._hi.push("  ")
 
     def depart_desc_signature(self, node: addnodes.desc_signature):
-        for id in node.get("ids", []):
-            self.body.append(f" <{id}>")
+        # Namespaced the same way as section headings (see depart_title())
+        # so that :py:class:, :confval:, etc. xrefs resolve consistently
+        # across the merged document.
+        docname = _doc_label(self.curfilestack[-1])
+        ids = node.get("ids", [])
+        if ids:
+            self.body.append(f" <{docname}:{ids[0]}>")
         self._hi.pop()
         self.body.append(f"{self._hi.prefix}],\n")
+        for node_id in ids[1:]:
+            self._write_anchor(f"{docname}:{node_id}")
 
     def visit_desc_name(self, node: addnodes.desc_name):
         self.body.append(f"{self._hi.indent}#strong(delta: 400)[")
@@ -171,8 +239,19 @@ def depart_index(self, node: addnodes.index):
         pass
 
     def visit_start_of_file(self, node: addnodes.start_of_file):
-        # NOTE: Implement this when rendering anything as the "start of file."
-        pass
+        # Track current document for cross-references (like LaTeX writer).
+        docname = node["docname"]
+        self.curfilestack.append(docname)
+        self._write_anchor(_doc_label(docname))
 
     def depart_start_of_file(self, node: addnodes.start_of_file):
-        pass
+        self.curfilestack.pop()
+
+    def _write_anchor(self, label: str) -> None:
+        # An invisible, addressable label that isn't attached to any
+        # visible content. Used to mark the start of a document - so a
+        # whole-document ``:doc:`` reference (which carries no section
+        # anchor) has something to link to even if that document has no
+        # sections - and for ids on a section beyond the first, which
+        # can't get a second label of their own (see depart_title()).
+        self.body.append(f"#metadata(none) <{label}>\n")
diff --git a/tests/test_e2e/test_it.py b/tests/test_e2e/test_it.py
index 358fb8d..d7f9f44 100644
--- a/tests/test_e2e/test_it.py
+++ b/tests/test_e2e/test_it.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from typing import TYPE_CHECKING
 
 import pytest
@@ -74,3 +75,130 @@ def test__copy_content_images(app: SphinxTestApp):
     assert (app.outdir / "index.typ").exists()
     assert (app.outdir / "_images/example.png").exists()
     assert (app.outdir / "_images/example.png").is_file()
+
+
+@pytest.mark.sphinx("typst", testroot="cross-references")
+def test__cross_references(app: SphinxTestApp):
+    """Test cross-referencing documents using :doc: role."""
+    app.build()
+    out = app.outdir / "index.typ"
+    assert out.exists()
+    content = out.read_text()
+    # Check that cross-reference content is present
+    assert "Cross-Reference Test Documentation" in content
+    # Verify that referenced pages are included in the main document
+    assert "Page 1" in content
+    assert "Page 2" in content
+    assert "Nested Page" in content
+    # Check that cross-references are converted to Typst links.
+    # A plain :doc: link carries no section anchor, so it points at the
+    # document-level label (see TypstTranslator._write_anchor()).
+    assert "#link(<page1>)" in content
+    assert "#link(<page2>)" in content
+    assert "#link(<subdir:nested>)" in content
+    assert "#link(<>)" not in content
+    # Verify that section labels are created for the first section of each document
+    assert "<page1:page-1>" in content
+    assert "<page2:page-2>" in content
+    assert "<subdir:nested:nested-page>" in content
+    # Verify content from referenced pages is included
+    assert "first page in our cross-reference test" in content
+    assert "second page in our cross-reference test" in content
+    assert "nested page in a subdirectory" in content
+    # Edge case: document without sections
+    assert "This document has no sections" in content
+    # Verify that a document-level label is generated for documents without sections
+    assert "#link(<no_sections>)" in content
+
+
+@pytest.mark.sphinx("typst", testroot="cross-references")
+def test__cross_references_ref_role_resolves_to_actual_target(app: SphinxTestApp):
+    """:ref: must resolve to the actual target, not be treated as a docname.
+
+    For ``:ref:`custom-target``` the target is the explicit
+    ``.. _custom-target:`` label in page2.rst, which is a distinct id from
+    the section's own auto-generated ``target-section`` id - :ref: must
+    resolve to the former, and that label must actually exist in the
+    output.
+    """
+    app.build()
+    content = (app.outdir / "index.typ").read_text()
+    assert "#link(<page2:custom-target>)" in content
+    assert content.count("<page2:custom-target>") >= 2
+
+
+@pytest.mark.sphinx("typst", testroot="cross-references")
+def test__cross_references_bare_relative_doc_path(app: SphinxTestApp):
+    """A bare relative :doc: target resolves to the current doc's directory.
+
+    Per Sphinx docs: ":doc:`parrot` occurring in sketches/index links to
+    sketches/parrot" - i.e. no ``../``/``./`` prefix is needed.
+    ``subdir/nested.rst`` references ``:doc:`sibling``` with no prefix, so
+    it must resolve to ``subdir/sibling``, not a top-level ``sibling``
+    document.
+    """
+    app.build()
+    content = (app.outdir / "index.typ").read_text()
+    assert "#link(<subdir:sibling>)" in content
+    assert "Sibling Page" in content
+
+
+@pytest.mark.sphinx("typst", testroot="cross-references")
+def test__cross_references_no_sections_label_is_actually_defined(app: SphinxTestApp):
+    """A no-sections document must not link to a label that's never emitted.
+
+    ``no_sections.rst`` has no headings, so it never gets a section label.
+    A whole-document ``:doc:`` reference to it must still resolve to some
+    label that is actually defined in the output (the document-level
+    anchor), not a dangling reference.
+    """
+    app.build()
+    content = (app.outdir / "index.typ").read_text()
+    assert "#link(<no_sections>)" in content
+    # One occurrence is the `#link(<no_sections>)` reference itself; a
+    # second, independent occurrence must exist as the actual label
+    # definition it points to.
+    assert content.count("<no_sections>") >= 2
+
+
+@pytest.mark.sphinx("typst", testroot="cross-references")
+def test__cross_references_implicit_title_uses_document_title(app: SphinxTestApp):
+    """Implicit-title :doc: must use the target document's title as link text.
+
+    Per Sphinx docs: "If no explicit link text is given... the link caption
+    will be the title of the given document."
+    """
+    app.build()
+    content = (app.outdir / "index.typ").read_text()
+    assert "#link(<page1>)[Page 1]" in content
+    assert "#link(<page2>)[Page 2]" in content
+
+
+@pytest.mark.sphinx("typst", testroot="cross-references")
+def test__cross_references_labels_use_valid_typst_syntax(app: SphinxTestApp):
+    """Every generated label must only use characters Typst's <label> syntax allows.
+
+    Per Typst's docs, a label's name may only contain letters, numbers, ``_``,
+    ``-``, ``:`` and ``.``. ``:confval:`my_option[]``` has a reftarget
+    containing ``[``/``]`` (mirroring this project's own real
+    ``typst_documents[].entrypoint`` confval), which is copied verbatim into
+    the generated label and breaks the Typst parser ("unclosed label").
+    """
+    app.build()
+    content = (app.outdir / "index.typ").read_text()
+    label_pattern = re.compile(r"<([^<>\s]+)>")
+    valid_label = re.compile(r"^[A-Za-z0-9_.:-]+$")
+    invalid = [m for m in label_pattern.findall(content) if not valid_label.match(m)]
+    assert invalid == []
+
+
+@pytest.mark.sphinx("typstpdf", testroot="cross-references")
+def test__cross_references_pdf_compiles(app: SphinxTestApp):
+    """The merged document with cross-references must still compile to PDF.
+
+    Combines several of the issues above (dangling labels, label characters
+    Typst rejects) into one end-to-end check that the generated Typst source
+    is actually valid.
+    """
+    app.build()
+    assert (app.outdir / "index.pdf").exists()
diff --git a/tests/testdocs/test-cross-references/conf.py b/tests/testdocs/test-cross-references/conf.py
new file mode 100644
index 0000000..16dcdb7
--- /dev/null
+++ b/tests/testdocs/test-cross-references/conf.py
@@ -0,0 +1,14 @@
+# noqa: D100
+
+extensions = [
+    "atsphinx.typst",
+]
+
+typst_documents = [
+    {
+        "entrypoint": "index",
+        "filename": "index",
+        "theme": "manual",
+        "title": "Cross-Reference Test Documentation",
+    }
+]
diff --git a/tests/testdocs/test-cross-references/index.rst b/tests/testdocs/test-cross-references/index.rst
new file mode 100644
index 0000000..9125c92
--- /dev/null
+++ b/tests/testdocs/test-cross-references/index.rst
@@ -0,0 +1,63 @@
+Cross-Reference Test Documentation
+===================================
+
+This document tests cross-referencing to other documents as described in the Sphinx documentation.
+
+Cross-Referencing Documents
+---------------------------
+
+Using the ``:doc:`` role to reference other documents:
+
+* Link to page1: :doc:`page1`
+* Link to page2: :doc:`page2`
+* Link to page1 with custom text: :doc:`First Page <page1>`
+* Link to page2 with custom text: :doc:`Second Page <page2>`
+
+Using absolute paths:
+
+* Absolute link to page1: :doc:`/page1`
+* Absolute link to page2: :doc:`/page2`
+
+Using relative paths with subdirectories:
+
+* Link to nested page: :doc:`subdir/nested`
+
+Cross-Referencing with Download Role
+-------------------------------------
+
+The ``:download:`` role can also reference documents:
+
+* Download link: :download:`page1.rst <page1.rst>`
+
+Other Reference Roles
+----------------------
+
+Sphinx resolves more than just ``:doc:`` through ``pending_xref`` nodes.
+These should keep working the same way they do without the Typst builder:
+
+* Ref to a named target in another document: :ref:`custom-target`
+* Confval-style target containing brackets: :confval:`my_option[]`
+
+.. confval:: my_option[]
+
+   A configuration value whose name contains brackets, like the real
+   ``typst_documents[].entrypoint`` confval used in this project's own docs.
+
+Edge Cases
+----------
+
+Testing edge cases:
+
+* Reference to document without sections: :doc:`no_sections`
+
+Table of Contents
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   page1
+   page2
+   subdir/nested
+   subdir/sibling
+   no_sections
diff --git a/tests/testdocs/test-cross-references/no_sections.rst b/tests/testdocs/test-cross-references/no_sections.rst
new file mode 100644
index 0000000..a90958d
--- /dev/null
+++ b/tests/testdocs/test-cross-references/no_sections.rst
@@ -0,0 +1,5 @@
+This document has no sections, only paragraphs.
+
+It contains some text but no section headings with IDs.
+
+This tests the fallback behavior when a document has no sections.
diff --git a/tests/testdocs/test-cross-references/page1.rst b/tests/testdocs/test-cross-references/page1.rst
new file mode 100644
index 0000000..d9d0bb1
--- /dev/null
+++ b/tests/testdocs/test-cross-references/page1.rst
@@ -0,0 +1,16 @@
+Page 1
+======
+
+This is the first page in our cross-reference test.
+
+Content
+-------
+
+This page contains some content that can be referenced from other documents.
+
+Back to Main Content
+--------------------
+
+You can go back to the main document.
+
+Or navigate to :doc:`page2`.
diff --git a/tests/testdocs/test-cross-references/page2.rst b/tests/testdocs/test-cross-references/page2.rst
new file mode 100644
index 0000000..5bf7566
--- /dev/null
+++ b/tests/testdocs/test-cross-references/page2.rst
@@ -0,0 +1,23 @@
+Page 2
+======
+
+This is the second page in our cross-reference test.
+
+More Content
+------------
+
+This page also contains content that can be referenced.
+
+Navigation
+----------
+
+* Back to the main document
+* Go to :doc:`page1`
+* Visit the :doc:`nested page <subdir/nested>`
+
+.. _custom-target:
+
+Target Section
+--------------
+
+This section is the target of a ``:ref:`` from the main document.
diff --git a/tests/testdocs/test-cross-references/subdir/nested.rst b/tests/testdocs/test-cross-references/subdir/nested.rst
new file mode 100644
index 0000000..44d3b70
--- /dev/null
+++ b/tests/testdocs/test-cross-references/subdir/nested.rst
@@ -0,0 +1,26 @@
+Nested Page
+===========
+
+This is a nested page in a subdirectory.
+
+Nested Content
+--------------
+
+This page demonstrates cross-referencing from a subdirectory.
+
+Navigation from Subdirectory
+-----------------------------
+
+* Back to the main document
+* Go to :doc:`../page1`
+* Go to :doc:`../page2`
+
+Using absolute paths:
+
+* Absolute link to page1: :doc:`/page1`
+
+Using a bare relative path (no ``../`` or ``./`` prefix), which per Sphinx
+docs resolves relative to this document's own directory, i.e. to
+``subdir/sibling``:
+
+* Bare relative link to sibling: :doc:`sibling`
diff --git a/tests/testdocs/test-cross-references/subdir/sibling.rst b/tests/testdocs/test-cross-references/subdir/sibling.rst
new file mode 100644
index 0000000..13da722
--- /dev/null
+++ b/tests/testdocs/test-cross-references/subdir/sibling.rst
@@ -0,0 +1,7 @@
+Sibling Page
+============
+
+This page lives next to ``nested.rst`` in the same subdirectory.
+
+It is the target of a bare relative ``:doc:`` reference (no ``../`` or
+``./`` prefix) from ``nested.rst``.