Edit on GitHub

Internals

QuantumCitations.CitationBibliography — Type

Plugin for enabling bibliographic citations in Documenter.jl.

bib = CitationBibliography(bibfile; style=:numeric)

instantiates a plugin that must be passed as an (undocumented!) positional argument to Documenter.makedocs.

Arguments

  • bibfile: the name of the BibTeX file from which to read the data.
  • style: the style to use for the bibliography and all citations. The available built-in styles are :numeric (default), :authoryear, and :alpha. With user-defined styles, this may be an arbitrary name of object.

Internal fields

The following internal fields are used by the citation pipeline steps. These should not be considered part of the stable API.

  • entries: dict of citation keys to entries in bibfile
  • citations: ordered dict of citation key to citation number
  • page_citations: dict of page file name to set of citation keys cited on page.
source

Citation Pipeline

The QuantumCitations.CitationBibliography plugin hooks into the Documenter.Builder.DocumentPipeline[1] between ExpandTemplates (which expands @docs blocks) and CrossReferences. The plugin adds the following three steps:

  1. CollectCitations
  2. ExpandBibliography
  3. ExpandCitations
QuantumCitations.CollectCitations — Type

Pipeline step to collect citations from all pages.

It walks all pages in the order they appear in the navigation bar, looking for @cite links. It fills the citations and page_citations attributes of the internal CitationBibliography object.

Thus, the order in which CollectCitations encounters citations determines the numerical key that will appear in the rendered documentation (see ExpandBibliography and ExpandCitations).

source
QuantumCitations.ExpandBibliography — Type

Pipeline step to expand all @bibliography blocks.

Runs after CollectCitations but before ExpandCitations.

Each bibliography is rendered into HTML as a a definition list, a bullet list, or an enumeration depending on bib_html_list_style. For a definition list, the label for each list item is rendered via format_bibliography_label and the full bibliographic reference is rendered via format_bibliography_reference. For bullet lists of enumerations, format_bibliography_label is not used and format_bibliography_reference fully determines the entry.

The order of the entries in the bibliography is determined by the bib_sorting method for the chosen citation style.

source

Customization

A custom style can be created by defining methods for functions listed below that specialize for a user-defined style argument to CitationBibliography. If the style is identified by a simple name, e.g. :mystyle, the method should specialize on Val{:mystyle}, see the examples for custom styles. Beyond that, e.g., if the style needs to implement options or needs to maintain internal state to manage unique citation labels, style can be an object of a custom type.

QuantumCitations.bib_html_list_style — Function

Identify the type of HTML list associated with a bibliographic style.

bib_html_list_style(style)

must return one of

  • :dl (definition list),
  • :ul (unordered / bullet list), or
  • :ol (ordered list / enumeration),

for any style that CitationBibliography is instantiated with.

source
QuantumCitations.format_bibliography_label — Function

Format the label for an entry in a @bibliography block.

format_bibliography_label(style, entry, citations)

produces a string for the label in the bibliography for the given Bibliography.Entry. The citations argument is a dict that maps citation keys (entry.id) to the order in which citations appear in the documentation, i.e., a numeric citation key.

For the default style=:numeric, this returns a label that is the numeric citation key in square brackets, cf. format_citation. In general, this function is used only if bib_html_list_style returns :dl for the given style.

source
QuantumCitations.format_bibliography_reference — Function

Format the full reference for an entry in a @bibliography block.

format_bibliography_reference(style, entry)

produces an HTML string for the full reference of a Bibliography.Entry. For the default style=:numeric, the result is formatted like in REVTeX and APS journals. That is, the full list of authors with initials for the first names, the italicized tile, and the journal reference (linking to the DOI, if available), ending with the publication year in parenthesis.

source
QuantumCitations.format_citation — Function

Format a @cite citation.

text = format_citation(
    style,
    entry,
    citations;
    note=nothing,
    cite_cmd=:cite,
    capitalize=false,
    starred=false
)

returns a string that replaces the link text for a markdown citation ([key](@cite) and its variations, see Syntax for Citations and the Citation Style Gallery).

For the default style=:numeric and [key](@cite), this returns a label that is the numeric citation key in square brackets, cf. format_bibliography_label.

Argument

  • style: The style to render the citation in, as passed to CitationBibliography
  • entry: The Bibliography.Entry that is being cited
  • citations: A dict that maps citation keys (entry.id) to the order in which citations appear in the documentation, i.e., a numeric citation index
  • note: A citation note, e.g. "Eq. (1)" in [GoerzQ2022; Eq. (1)](@cite)
  • cite_cmd: The citation command, one of :cite, :citet, :citep. Note that, e.g., [Goerz@2022](@Citet*) results in cite_cmd=:citet
  • capitalize: Whether the citation should be formatted to appear at the start of a sentence, as indicated by a capitalized @Cite... command, e.g., [GoerzQ2022](@Citet*)
  • starred: Whether the citation should be rendered in "extended" form, i.e., with the full list of authors, as indicated by a * in the citation, e.g., [Goerz@2022](@Citet*)
source

Debugging

Set the environment variable JULIA_DEBUG=Documenter,QuantumCitations before generating the documentation.