describe_citation

documenteer.citations.describe_citation(citation, citations, *, unlabelled_field='bibtex_key')

Name one citation in a build warning, so that a reader can tell which of a site’s entries it is about.

Parameters:

• citation (Mapping[str, Any]) – The citation to name, as the mapping GuideCitation.to_html_context composes and Sphinx’s html_context publishes.

• citations (Sequence[Mapping[str, Any]]) – Every citation the site declares, consulted only to learn whether this one’s label is shared.

• unlabelled_field (str, default: 'bibtex_key') – The field naming an entry that declares no label. The BibTeX key is the default because every entry resolves one; a warning whose subject is a field the key is composed from names that field instead.

Returns:

The entry’s label, quoted – with its BibTeX key appended in parentheses when another entry carries the same label.

Return type:

str

Notes

A label is a display string: it says what the reader needs to see at the spot the citation appears, so a site with a registered landing page per data product writes label = "TAP" on every one of them. Identity belongs to the BibTeX key, which the configuration keeps unique across the site. Naming a shared label alone would leave a warning pointing at forty entries at once, and naming every entry by its key would spell out a DOI where a site with distinct labels reads perfectly well, so the key is added exactly when the label stops being enough.