Referencing Styles

Base Classes For Composing Styles

class sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle

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 (unless init=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.

inner(role_name: str) → Node

Returns inner template for formatting the references.

outer(role_name: str, children: List[BaseText]) → Node

Returns outer template for formatting the references.

role_names() → Iterable[str]

Get list of role names supported by this style.

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)

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.

left: Union[BaseText, str] = '['

Left bracket.

outer(children: List[BaseText], brackets=False, capfirst=False) → Node

Creates an outer template with separators, adding brackets if requested, and capitalizing the first word if requested.

right: Union[BaseText, str] = ']'

Right bracket.

sep: Union[BaseText, str] = ', '

Separators used for outer template (i.e. in between references if multiple keys are referenced in a single citation).

sep2: Optional[Union[BaseText, str]] = None

Separator for outer template, if only two items.

class sphinxcontrib.bibtex.style.referencing.GroupReferenceStyle(styles: List[sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, role_style: Dict[str, sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>)

Composes a group of reference styles into a single consistent style.

inner(role_name: str) → Node

Gets the inner template associated with role_name in one of the styles.

outer(role_name: str, children: List[BaseText]) → Node

Gets the outer template associated with role_name in one of the styles.

role_names()

Get list of role names supported by this style.

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.')))

A class providing additional data and helper functions to facilitate formatting of person names.

abbreviate: bool = True

Whether or not to abbreviate first 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

Returns a template formatting the persons with correct separators and using the full person list if so requested.

other: Optional[Union[BaseText, str]] = Text(' ', Tag('em', 'et al.'))

Abbreviation text if three or more persons.

sep: Union[BaseText, str] = ', '

Separator between persons.

sep2: Optional[Union[BaseText, str]] = ' and '

Separator between persons, if only two persons.

style: str = 'last'

Plugin name of the style used for formatting person names.

style_plugin: BaseNameStyle

Plugin class instance used for formatting person names. Automatically initialised from style.

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

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’s get_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.'))))

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.

inner(role_name: str) → Node

Returns inner template for formatting the references.

outer(role_name: str, children: List[BaseText]) → Node

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.

role_names() → Iterable[str]

Get list of role names supported by this 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.'))))

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.

inner(role_name: str) → Node

Returns inner template for formatting the references.

outer(role_name: str, children: List[BaseText]) → Node

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.

role_names() → Iterable[str]

Get list of role names supported by this 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] = ', ')

Parenthetical reference by author-year.

author_year_sep: Union[BaseText, str] = ', '

Separator between author and year.

bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)

Bracket style.

inner(role_name: str) → Node

Returns inner template for formatting the references.

outer(role_name: str, children: List[BaseText]) → Node

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.

role_names() → Iterable[str]

Get list of role names supported by this 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.'))))

Textual reference by author-year.

bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)

Bracket style.

inner(role_name: str) → Node

Returns inner template for formatting the references.

outer(role_name: str, children: List[BaseText]) → Node

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.

role_names() → Iterable[str]

Get list of role names supported by this 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))

Reference just by label.

bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)

Bracket style.

inner(role_name: str) → Node

Returns inner template for formatting the references.

outer(role_name: str, children: List[BaseText]) → Node

Returns outer template for formatting the references.

role_names() → Iterable[str]

Get list of role names supported by this 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.'))))

Reference just by author names.

bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)

Bracket style.

inner(role_name: str) → Node

Returns inner template for formatting the references.

outer(role_name: str, children: List[BaseText]) → Node

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.

role_names() → Iterable[str]

Get list of role names supported by this style.

class sphinxcontrib.bibtex.style.referencing.extra_year.ExtraYearReferenceStyle(bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None))

Reference just by year.

bracket: sphinxcontrib.bibtex.style.referencing.BracketStyle = BracketStyle(left='[', right=']', sep=', ', sep2=None, last_sep=None)

Bracket style.

inner(role_name: str) → Node

Returns inner template for formatting the references.

outer(role_name: str, children: List[BaseText]) → Node

Returns outer template for formatting the references.

role_names() → Iterable[str]

Get list of role names supported by this 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.'))))

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] = ', ')

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).