compose_landing_page_jsonld#

documenteer.citations.compose_landing_page_jsonld(citations, *, site_url=None, site_title=None)#

Compose a site’s citations as a schema.org JSON-LD document, serialized ready to embed in a <script type="application/ld+json"> element.

Parameters:

citations (Sequence[Mapping[str, Any]]) – The site’s citations, each as the mapping GuideCitation.to_html_context composes and Sphinx’s html_context publishes.
site_url (str | None, default: None) – The site’s own base URL, used as the url of the document’s subject — the self citation’s node, or the site’s own node when no entry is the self citation.
site_title (str | None, default: None) – The site’s own title, used as the name of the site’s own node. Unused when an entry is the self citation, whose own title names the subject.

Returns:

The serialized JSON-LD document, or None when no citation belongs in it — a site that declares none, and one whose entries are neither parts, nor preferred, nor shown in the footer, emits no block at all.

Return type:

str | None

Notes

The self citation is the document’s own subject rather than one node among several: this page is that DOI’s landing page, so a consumer reading the document top-level finds the DOI it came for. Every other entry reaches the document as a relation of that subject, and which relation it is follows from whether the entry claims a landing page of its own:

An entry that sets GuideCitation.page is a part of the site’s own work — a data product of a release, not something the site cites — so it is named in hasPart by reference alone (see _minimal_reference). Its full record belongs on the page it claims, which compose_page_jsonld composes.
An entry with no page is a work the site cites, and reaches citation in full. The site’s preferred entry always does: it is by definition the citation the site asks readers to use, which is exactly what schema.org citation on the site’s own node states, whether or not the footer repeats it. Every other entry reaches citation only when the footer shows it — an additional work that appears nowhere on the page is not something a consumer of this page needs the whole record of, and repeating it on all of them is weight every page pays for.

GuideCitation.in_footer therefore governs a visual surface and, for the additional entries alone, whether the metadata carries them. A site that writes in_footer = false on its preferred citation — the shape an API-heavy guide takes, where a “How to cite” block under every autodoc stub is noise — silences that surface and keeps the citation in the metadata every page of it publishes.

An entry that is neither a part, nor preferred, nor shown in the footer therefore appears in no site-wide block, though a citation-card that names it still renders it.

A site that declares citations but marks none of them self — one whose preferred citation is a work published elsewhere, whose landing page is that publisher’s — is still the subject of its own document. It is described as a WebSite carrying the site’s title and URL and no identifier at all (see _site_node), and the same entries reach it under the same two relations, in the same shapes: a part by reference, a cited work in full. Only the subject differs, so the rule a consumer reads the block by does not depend on whether the site publishes a DOI of its own.

The returned string is safe to place directly in a <script> element: the characters that could close it early are written as JSON string escapes (see _SCRIPT_ESCAPES), so a title containing </script>, quotes, or ampersands cannot break out of the block.