Internals
DocumenterCitations.CitationBibliography
— TypePlugin for enabling bibliographic citations in Documenter.jl.
bib = CitationBibliography(bibfile; style=:numeric)
instantiates a plugin object that must be passed as an element of the plugins
keyword 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 or 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 inbibfile
citations
: ordered dict of citation key to citation numberpage_citations
: dict of page file name to set of citation keys cited on page.anchor_map
: anAnchorMap
object that keeps track of the link anchors for references in bibliography blocks
Citation Pipeline
The DocumenterCitations.CitationBibliography
plugin hooks into the Documenter.Builder.DocumentPipeline
[1] between ExpandTemplates
(which expands @docs
blocks) and CrossReferences
. The plugin adds the following three steps:
DocumenterCitations.CollectCitations
— TypePipeline 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
).
DocumenterCitations.ExpandBibliography
— TypePipeline 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 or 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.
The ExpandBibliography
step runs init_bibliography!
before expanding the first @bibliography
block.
DocumenterCitations.ExpandCitations
— TypePipeline step to expand all @cite
citations.
This runs after ExpandBibliography
, as it relies on the link targets in the expanded @bibliography
blocks.
All citations are formatted using format_citation
.
Customization
A custom style can be created by defining methods for the 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 methods 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. The builtin DocumenterCitations.AlphaStyle
is an example for such a "stateful" style, initialized via a custom init_bibliography!
method.
DocumenterCitations.bib_html_list_style
— FunctionIdentify 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.
DocumenterCitations.bib_sorting
— FunctionIdentify the sorting associated with a bibliographic style.
bib_sorting(style)
must return :citation
or any of the sorting_rules
accepted by Bibliography.sort_bibliography!
, e.g. :nyt
.
DocumenterCitations.format_bibliography_label
— FunctionFormat 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
.
DocumenterCitations.format_bibliography_reference
— FunctionFormat 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.
DocumenterCitations.format_citation
— FunctionFormat 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 toCitationBibliography
entry
: TheBibliography.Entry
that is being citedcitations
: A dict that maps citation keys (entry.id
) to the order in which citations appear in the documentation, i.e., a numeric citation indexnote
: 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 incite_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*)
DocumenterCitations.init_bibliography!
— FunctionInitialize any internal state for rendering the bibliography.
init_bibliography!(style, bib)
is called at the beginning of the ExpandBibliography
pipeline step. It may mutate internal fields of style
or bib
to prepare for the rendering of bibliography blocks.
For the default style, this does nothing.
For, e.g., AlphaStyle
, the call to init_bibliography!
determines the citation labels, by generating unique suffixed labels for all the entries in the underlying .bib
file (bib.entries
), and storing the result in an internal attribute of the style
object.
Custom styles may implement a new method for init_bibliography!
for similar purposes. It can be assumed that all the internal fields of the CitationBibliography
bib
object are up-to-date according to the citations seen by the earlier CollectCitations
step.
Debugging
Set the environment variable JULIA_DEBUG=Documenter,DocumenterCitations
before generating the documentation.
- 1See the documentation of
Documenter.Selectors
for an explanation of Documenter's pipeline concept.