Referencing Styles¶
Base Classes For Composing Styles¶
- class sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle[source]¶
Base class for citation reference styles.
For consistency, all subclasses of this class must be decorated as a
dataclasses.dataclass
, and must provide a type annotation and default value for all attributes (unlessinit=False
is used, in which case they can be initialized in__post_init__()
). This allows client code to instantiate any reference style without needing to specify any arguments through the constructor.
- class sphinxcontrib.bibtex.style.referencing.BracketStyle(left: Union[BaseText, str] = '[', right: Union[BaseText, str] = ']', sep: Union[BaseText, str] = ', ', sep2: Optional[Union[BaseText, str]] = None, last_sep: Optional[Union[BaseText, str]] = None)[source]¶
A class which provides brackets, as well as separators and a function to facilitate formatting of the outer template.
- last_sep: Optional[Union[BaseText, str]] = None¶
Separator for outer template, for last item if three or more items.
- outer(children: List[BaseText], brackets=False, capfirst=False) Node [source]¶
Creates an outer template with separators, adding brackets if requested, and capitalizing the first word if requested.
- class sphinxcontrib.bibtex.style.referencing.GroupReferenceStyle(styles: List[sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, role_style: Dict[str, sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>)[source]¶
Composes a group of reference styles into a single consistent style.
- inner(role_name: str) Node [source]¶
Gets the inner template associated with role_name in one of the
styles
.
- outer(role_name: str, children: List[BaseText]) Node [source]¶
Gets the outer template associated with role_name in one of the
styles
.
- role_style: Dict[str, sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle]¶
Dictionary from role names to styles. Automatically initialized from
styles
.
- styles: List[sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle]¶
List of style types.
- class sphinxcontrib.bibtex.style.referencing.PersonStyle(style: str = 'last', abbreviate: bool = True, sep: Union[BaseText, str] = ', ', sep2: Optional[Union[BaseText, str]] = ' and ', last_sep: Optional[Union[BaseText, str]] = ', and ', other: Optional[Union[BaseText, str]] = Text(' ', Tag('em', 'et al.')))[source]¶
A class providing additional data and helper functions to facilitate formatting of person names.
- last_sep: Optional[Union[BaseText, str]] = ', and '¶
Separator between persons, for last person if three or more persons.
- names(role: str, full: bool) Node [source]¶
Returns a template formatting the persons with correct separators and using the full person list if so requested.
- sphinxcontrib.bibtex.style.referencing.format_references(style: sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle, reference_text_class: Type[sphinxcontrib.bibtex.richtext.BaseReferenceText[sphinxcontrib.bibtex.richtext.ReferenceInfo]], role_name: str, references: Iterable[Tuple[Entry, FormattedEntry, sphinxcontrib.bibtex.richtext.ReferenceInfo]]) BaseText [source]¶
Format the list of references according to the given role.
First formats each reference using the style’s
get_inner()
method, then joins all these formatted references together using the style’sget_outer()
method.
Basic Styles¶
Basic styles that support both textual and parenthetical citations.
Should provide roles with names
p
, ps
, t
, ts
, ct
, and cts
.
Here, t
stands for textual and p
for parenthetical.
The c
prefix causes the first letter to be capitalized,
and the s
suffix causes all authors to be named rather than
shortening the list using “et al.” or some other suffix as
specified by the style.
- class sphinxcontrib.bibtex.style.referencing.basic_label.BasicLabelParentheticalReferenceStyle(bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.'))))[source]¶
Reference by label if parenthetical, and by author and label if textual.
- bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style.
- outer(role_name: str, children: List[BaseText]) Node [source]¶
Returns outer template for formatting the references.
- person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.')))¶
Person style.
- class sphinxcontrib.bibtex.style.referencing.basic_label.BasicLabelTextualReferenceStyle(bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.'))), text_reference_sep: Union[BaseText, str] = ' ')[source]¶
Reference by label if parenthetical, and by author and label if textual.
- bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style.
- outer(role_name: str, children: List[BaseText]) Node [source]¶
Returns outer template for formatting the references.
- person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.')))¶
Person style.
- class sphinxcontrib.bibtex.style.referencing.basic_author_year.BasicAuthorYearParentheticalReferenceStyle(bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.'))), author_year_sep: Union[BaseText, str] = ', ')[source]¶
Parenthetical reference by author-year.
- bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style.
- outer(role_name: str, children: List[BaseText]) Node [source]¶
Returns outer template for formatting the references.
- person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.')))¶
Person style.
- class sphinxcontrib.bibtex.style.referencing.basic_author_year.BasicAuthorYearTextualReferenceStyle(bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.'))), text_reference_sep: Union[BaseText, str] = ' ')[source]¶
Textual reference by author-year.
- bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style.
- outer(role_name: str, children: List[BaseText]) Node [source]¶
Returns outer template for formatting the references.
- person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.')))¶
Person style.
Extra Styles¶
For styles providing additional roles, e.g. for citations that
specifically use the label, the author, the year, etc.
The convention for these styles is to have one role for producing
whichever text needs to be had, and to have a par
suffix
in the role name if the citation text needs to be embedded in
brackets (for example label
and labelpar
).
- class sphinxcontrib.bibtex.style.referencing.extra_label.ExtraLabelReferenceStyle(bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None))[source]¶
Reference just by label.
- bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style.
- class sphinxcontrib.bibtex.style.referencing.extra_author.ExtraAuthorReferenceStyle(bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.'))))[source]¶
Reference just by author names.
- bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style.
- outer(role_name: str, children: List[BaseText]) Node [source]¶
Returns outer template for formatting the references.
- person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.')))¶
Person style.
- class sphinxcontrib.bibtex.style.referencing.extra_year.ExtraYearReferenceStyle(bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None))[source]¶
Reference just by year.
- bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style.
Full Styles¶
For styles that combine a basic style with one or more extra styles.
- class sphinxcontrib.bibtex.style.referencing.label.LabelReferenceStyle(styles: List[sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, role_style: Dict[str, sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, bracket_textual: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), bracket_parenthetical: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), bracket_author: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), bracket_label: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), bracket_year: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.'))), text_reference_sep: Union[BaseText, str] = ' ')[source]¶
Textual or parenthetical reference by label, or just by author, label, or year.
- bracket_author: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for author citations (:cite:author: and variations).
- bracket_label: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for label citations (:cite:label: and variations).
- bracket_parenthetical: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for parenthetical citations (:cite:p: and variations).
- bracket_textual: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for textual citations (:cite:t: and variations).
- bracket_year: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for year citations (:cite:year: and variations).
- person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.')))¶
Person style.
- class sphinxcontrib.bibtex.style.referencing.author_year.AuthorYearReferenceStyle(styles: List[sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, role_style: Dict[str, sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, bracket_textual: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), bracket_parenthetical: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), bracket_author: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), bracket_label: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), bracket_year: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None), person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.'))), author_year_sep: Union[BaseText, str] = ', ', text_reference_sep: Union[BaseText, str] = ' ')[source]¶
Textual or parenthetical reference by author-year, or just by author, label, or year.
- author_year_sep: Union[BaseText, str] = ', '¶
Separator between author and year for parenthetical citations.
- bracket_author: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for author citations (:cite:author: and variations).
- bracket_label: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for label citations (:cite:label: and variations).
- bracket_parenthetical: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for parenthetical citations (:cite:p: and variations).
- bracket_textual: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for textual citations (:cite:t: and variations).
- bracket_year: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)¶
Bracket style for year citations (:cite:year: and variations).
- person: sphinxcontrib.bibtex.style.referencing.PersonStyle = PersonStyle(style='last', style_plugin=<sphinxcontrib.bibtex.style.names.last.LastNameStyle object>, abbreviate=True, sep=', ', sep2=' and ', last_sep=', and ', other=Text(' ', Tag('em', 'et al.')))¶
Person style (applies to all relevant citation commands).