Cross-references

papyri's reason for existing is cross-linking, so references get their own page: internal labels, API object refs, external links, citations, and footnotes.

Internal label references

Any .. _label: target can be linked from anywhere in the same bundle with the :ref: role. This page defines the target below:

Referencing across pages works the same way — back to the specimen index, or to a sibling page such as admonitions. Within a page you can jump to a local anchor: the anchor defined just above.

When the bracketed text is omitted, the link text falls back to the target's section title: specimen-inline.

API object references

The Python-domain roles link to documented API objects. They resolve when the bundle also contains API docs for the target (built without --no-api); unresolved targets render with a distinct "unresolved" style so broken links are visible rather than silent.

• Module: papyri

• Class: papyri.gen.Gen

• Method: papyri.gen.Gen.collect_narrative_docs

• Function: papyri.gen.Gen

The same roles cross packages: a papyri doc can link straight to numpy.linspace. The viewer resolves such a reference against an ingested numpy bundle if one is present, or — failing that — against a registered external numpy inventory (see below). With neither in place the target renders unresolved, which is exactly how a dangling cross-package link looks.

External API references (intersphinx)

A cross-package reference whose target is importable at gen time but lives outside any ingested bundle can still be linked, by resolving it against a Sphinx objects.inv inventory registered with the viewer (Admin → External inventories, or POST /api/inventory). This is how a papyri bundle links into projects that don't ship a DocBundle — numpy, scipy, or the Python standard library:

• Class: pathlib.Path

• Function: json.loads

• Class: datetime.datetime

• Class: collections.OrderedDict

• Module: collections

• Function: functools.partial

• Function: re.compile

• Class: collections.abc.Mapping

Resolution is by object name, like intersphinx itself: the dotted name is looked up across every registered inventory, preferring one whose project name matches the reference's top-level module. So a single Python inventory — https://docs.python.org/3/objects.inv registered as python — resolves references into any stdlib module above (pathlib.Path, json.loads, collections.abc.Mapping, …), even though gen records each object's real top-level module (pathlib, json, collections). A resolved external link renders as an external xref with a trailing arrow; a name that is in no registered inventory stays unresolved, like any other cross-package miss.

• C-accelerated stdlib objects. A reference resolves via the object's real defining module, which for C-accelerated callables is a private module: os.getcwd resolves to posix.getcwd and os.path.join to posixpath.join, neither of which matches the public name on docs.python.org. Prefer pure-Python targets (as above) for external links.

External links

An inline external link wraps the text and trails a double underscore: the papyri repository.

A named target lets you reuse a URL by name:

Report problems on the papyri issues tracker. The target is defined once and referenced by name.

PEP, pull-request, and issue roles

• Pep 440 — links to the version-identifier PEP on python.org.

• #1 — links to a pull request in the configured GitHub repo.

• #1 — links to an issue in the same repo.

Citations

Citations are named references collected at the bottom of the document. Cite inline with [label]_ and define with .. [label]:

The split-pipeline design follows the conda-forge publishing model [condaforge], and the IR is encoded with CBOR [RFC8949].

Footnotes

Footnotes use [#label]_ for auto-numbered notes that render at the foot of the page:

papyri targets Python 3.13 and newer ^[1], and the viewer runs on both Node.js and Cloudflare Workers ^[2].

The :doc: role

The :doc: role links to another narrative document by path rather than by label: :doc:`inline`. Prefer :ref: with an explicit .. _label: target where possible — label resolution is bundle-wide and does not depend on the on-disk path of either document.