GuideCitation#

class documenteer.citations.GuideCitation(*, citation, label=None, is_self=False, is_preferred=False, in_footer=False, note=None, page=None, page_fragment=None, cff=None, bibtex_key=None, cff_preferred=True)#

Bases: object

A citation a user guide displays, together with how the guide presents it.

A guide declares these in the [[project.citations]] array of documenteer.toml. The bibliographic record is the Citation; the remaining fields say where and how the guide shows it, and are set in documenteer.toml alone — they are never sourced from a CITATION.cff file.

Parameters:

citation (Citation)
label (str | None, default: None)
is_self (bool, default: False)
is_preferred (bool, default: False)
in_footer (bool, default: False)
note (str | None, default: None)
page (str | None, default: None)
page_fragment (str | None, default: None)
cff (str | None, default: None)
bibtex_key (str | None, default: None)
cff_preferred (bool, default: True)

Attributes Summary

`bibtex_key`	The key this citation's BibTeX entry is written under, or `None` to let the citation compose its own (see `Citation.bibtex_key`).
`cff`	The path of the `CITATION.cff` file the bibliographic fields came from, as `documenteer.toml` wrote it, or `None` when the entry states them itself.
`cff_preferred`	its `preferred-citation` when true, as GitHub's "Cite this repository" button reads it, and its top-level record when false.
`citation`	The bibliographic record.
`in_footer`	Whether this citation appears in the site footer.
`is_preferred`	Whether this is the citation the site asks readers to use.
`is_self`	Whether this is the DOI whose landing page this site is.
`label`	A short display label distinguishing this citation from the others, such as "Dataset" or "Paper".
`note`	Free text about when to use this citation, displayed alongside it.
`page`	The docname of the page inside the site that is this DOI's landing page, or `None` when the site as a whole is.
`page_fragment`	The fragment identifier within `page` that names this work, without its leading `#`, or `None` when the whole page is the landing page.

Methods Summary

to_html_context()

Express the citation as the mapping published into Sphinx's html_context.

Attributes Documentation

bibtex_key: str | None = None#

The key this citation’s BibTeX entry is written under, or None to let the citation compose its own (see Citation.bibtex_key).

A guide resolves the key against its whole [[project.citations]] array — a site’s own work is keyed by its lsst.io subdomain, a work with a DOI by the DOI, and anything left over by author, year, and title — because only there are the site’s base URL and its other entries in hand. What reaches here is that answer, already decided.

cff: str | None = None#

The path of the CITATION.cff file the bibliographic fields came from, as documenteer.toml wrote it, or None when the entry states them itself.

This is provenance rather than presentation, and it is carried for one reason: a build that reports a field the citation does not state has to name the file the value would be set in, and the path a reader can act on is the relative one they wrote – not the absolute one it resolves to.

cff_preferred: bool = True#

its preferred-citation when true, as GitHub’s “Cite this repository” button reads it, and its top-level record when false.

Meaningless when cff is None; the configuration rejects setting it without one.

Type:: Which record of cff supplied the fields

citation: Citation = <dataclasses._MISSING_TYPE object>#: The bibliographic record.

in_footer: bool = False#: Whether this citation appears in the site footer.

is_preferred: bool = False#

Whether this is the citation the site asks readers to use.

At most one citation on a site is the preferred one. It is the entry a citation-card directive renders when given no label, and the one whose footer appearance is the default rather than opt-in.

is_self: bool = False#

Whether this is the DOI whose landing page this site is.

At most one citation on a site is the self citation. It is the one whose metadata the site emits in its <head>, and the subject of the site-wide JSON-LD block.

This says nothing about which citation the site asks readers to use — that is is_preferred. The two coincide for a site that publishes its own DOI, and part ways for one whose preferred citation is a work published somewhere else, whose landing page is that publisher’s.

label: str | None = None#: A short display label distinguishing this citation from the others, such as “Dataset” or “Paper”.

note: str | None = None#: Free text about when to use this citation, displayed alongside it.

page: str | None = None#

The docname of the page inside the site that is this DOI’s landing page, or None when the site as a whole is.

A site can be the landing page of one DOI, but a site that publishes several works can register a page of its own for each — a per-product page in a data release’s documentation, say. That page, rather than every page of the site, is the one that carries this citation’s machine-readable metadata.

page_fragment: str | None = None#

The fragment identifier within page that names this work, without its leading #, or None when the whole page is the landing page.

Several works can share a page and be told apart by their fragments, which is why the fragment is carried separately from the docname.

Methods Documentation

to_html_context()#

Express the citation as the mapping published into Sphinx’s html_context.

Returns:: A JSON-serializable mapping. Everything a template or a directive needs is precomputed here — including the plain_text and bibtex renderings — so that the surfaces that display a citation only read the context and never recompose it.
Return type:: dict[str, Any]

Notes

The mapping is the contract between this module and every guide surface that displays a citation: the <head> metadata, the citation-card directive, and the footer.

A displayed citation ends in a hyperlink to the work, so the mapping carries the plain-text rendering pre-split at that location: plain_text_lead is the citation up to it and plain_text_url is the location itself, and concatenating the two always reproduces plain_text. The split comes from Citation.to_plain_text_parts, which is where that invariant lives; publishing it here is what lets a Jinja template render a linked citation without doing string surgery of its own.

bibtex_key is the key the composed bibtex entry is written under, carried on its own so that a surface can name the key a reader will \cite without parsing the entry back apart.