GuideCitation#

class documenteer.citations.GuideCitation(*, citation, label=None, is_self=False, in_footer=False, note=None)#

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)
in_footer (bool, default: False)
note (str | None, default: None)

Attributes Summary

`citation`	The bibliographic record.
`in_footer`	Whether this citation appears in the site footer.
`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.

Methods Summary

to_html_context()

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

Attributes Documentation

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

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

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 one a citation-card directive renders by default.

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.

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. Splitting it here is what lets a Jinja template render a linked citation without doing string surgery of its own, and keeps the card and the footer from ever disagreeing about where the text ends and the link begins.