# 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 `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: BaseText | str = '[', right: BaseText | str = ']', sep: BaseText | str = ', ', sep2: BaseText | str | None = None, last_sep: BaseText | str | None = None)

  A class which provides brackets, as well as separators and a function to facilitate formatting of the outer template.

  last_sep: BaseText | str | None = None

    Separator for outer template, for last item if three or more items.

  left: 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: BaseText | str = ']'

    Right bracket.

  sep: BaseText | str = ', '

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

  sep2: BaseText | str | None = None

    Separator for outer template, if only two items.

class sphinxcontrib.bibtex.style.referencing.GroupReferenceStyle(styles: ~typing.List[~sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, role_style: ~typing.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, BaseReferenceStyle]

    Dictionary from role names to styles. Automatically initialized from `styles`.

  styles: List[BaseReferenceStyle]

    List of style types.

class sphinxcontrib.bibtex.style.referencing.PersonStyle(style: str = 'last', abbreviate: bool = True, sep: BaseText | str = ', ', sep2: BaseText | str | None = ' and ', last_sep: BaseText | str | None = ', and ', other: BaseText | str | None = <factory>)

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

  abbreviate: bool = True

    Whether to abbreviate first names.

  author_or_editor_or_title(full: bool) → Node

    Returns a template formatting the author, falling back on editor or title if author is not specified.

  last_sep: BaseText | str | None = ', 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: BaseText | str | None

    Abbreviation text if three or more persons.

  sep: BaseText | str = ', '

    Separator between persons.

  sep2: BaseText | str | None = ' 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: BaseReferenceStyle, role_name: str, references: Iterable[Tuple[Entry, FormattedEntry, ReferenceInfo]]) → BaseText

  Format the list of references according to the given role.

  First formats each reference using the style’s `inner()` method, then joins all these formatted references together using the style’s `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 = <factory>, pre_text_sep: BaseText | str = ' ', post_text_sep: BaseText | str = ', ')

  Reference by label if parenthetical, and by author and label if textual.

  bracket: BracketStyle

    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.

  post_text_sep: BaseText | str = ', '

    Separator between citation and post-text.

  pre_text_sep: BaseText | str = ' '

    Separator between pre-text and citation.

  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 = <factory>, person: ~sphinxcontrib.bibtex.style.referencing.PersonStyle = <factory>, text_reference_sep: BaseText | str = ' ', pre_text_sep: BaseText | str = ' ', post_text_sep: BaseText | str = ', ')

  Reference by label if parenthetical, and by author and label if textual.

  bracket: BracketStyle

    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: PersonStyle

    Person style.

  post_text_sep: BaseText | str = ', '

    Separator between citation and post-text.

  pre_text_sep: BaseText | str = ' '

    Separator between pre-text and citation.

  role_names() → Iterable[str]

    Get list of role names supported by this style.

  text_reference_sep: BaseText | str = ' '

    Separator between text and reference.

class sphinxcontrib.bibtex.style.referencing.basic_author_year.BasicAuthorYearParentheticalReferenceStyle(bracket: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, person: ~sphinxcontrib.bibtex.style.referencing.PersonStyle = <factory>, author_year_sep: BaseText | str = ', ', pre_text_sep: BaseText | str = ' ', post_text_sep: BaseText | str = ', ')

  Parenthetical reference by author-year.

  author_year_sep: BaseText | str = ', '

    Separator between author and year.

  bracket: BracketStyle

    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: PersonStyle

    Person style.

  post_text_sep: BaseText | str = ', '

    Separator between citation and post-text.

  pre_text_sep: BaseText | str = ' '

    Separator between pre-text and citation.

  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 = <factory>, person: ~sphinxcontrib.bibtex.style.referencing.PersonStyle = <factory>, text_reference_sep: BaseText | str = ' ', pre_text_sep: BaseText | str = ' ', post_text_sep: BaseText | str = ', ')

  Textual reference by author-year.

  bracket: BracketStyle

    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: PersonStyle

    Person style.

  post_text_sep: BaseText | str = ', '

    Separator between citation and post-text.

  pre_text_sep: BaseText | str = ' '

    Separator between pre-text and citation.

  role_names() → Iterable[str]

    Get list of role names supported by this style.

  text_reference_sep: BaseText | str = ' '

    Separator between text and reference.

## 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 = <factory>)

  Reference just by label.

  bracket: BracketStyle

    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 = <factory>, person: ~sphinxcontrib.bibtex.style.referencing.PersonStyle = <factory>)

  Reference just by author names.

  bracket: BracketStyle

    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: PersonStyle

    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 = <factory>)

  Reference just by year.

  bracket: BracketStyle

    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: ~typing.List[~sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, role_style: ~typing.Dict[str, ~sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, bracket_textual: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, bracket_parenthetical: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, bracket_author: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, bracket_label: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, bracket_year: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, person: ~sphinxcontrib.bibtex.style.referencing.PersonStyle = <factory>, text_reference_sep: BaseText | str = ' ', pre_text_sep: BaseText | str = ' ', post_text_sep: BaseText | str = ', ')

  Textual or parenthetical reference by label, or just by author, label, or year.

  bracket_author: BracketStyle

    Bracket style for author citations (:cite:author: and variations).

  bracket_label: BracketStyle

    Bracket style for label citations (:cite:label: and variations).

  bracket_parenthetical: BracketStyle

    Bracket style for parenthetical citations (:cite:p: and variations).

  bracket_textual: BracketStyle

    Bracket style for textual citations (:cite:t: and variations).

  bracket_year: BracketStyle

    Bracket style for year citations (:cite:year: and variations).

  person: PersonStyle

    Person style.

  post_text_sep: BaseText | str = ', '

    Separator between citation and post-text.

  pre_text_sep: BaseText | str = ' '

    Separator between pre-text and citation.

  text_reference_sep: BaseText | str = ' '

    Separator between text and reference for textual citations.

class sphinxcontrib.bibtex.style.referencing.author_year.AuthorYearReferenceStyle(styles: ~typing.List[~sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, role_style: ~typing.Dict[str, ~sphinxcontrib.bibtex.style.referencing.BaseReferenceStyle] = <factory>, bracket_textual: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, bracket_parenthetical: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, bracket_author: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, bracket_label: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, bracket_year: ~sphinxcontrib.bibtex.style.referencing.BracketStyle = <factory>, person: ~sphinxcontrib.bibtex.style.referencing.PersonStyle = <factory>, author_year_sep: BaseText | str = ', ', text_reference_sep: BaseText | str = ' ', pre_text_sep: BaseText | str = ' ', post_text_sep: BaseText | str = ', ')

  Textual or parenthetical reference by author-year, or just by author, label, or year.

  author_year_sep: BaseText | str = ', '

    Separator between author and year for parenthetical citations.

  bracket_author: BracketStyle

    Bracket style for author citations (:cite:author: and variations).

  bracket_label: BracketStyle

    Bracket style for label citations (:cite:label: and variations).

  bracket_parenthetical: BracketStyle

    Bracket style for parenthetical citations (:cite:p: and variations).

  bracket_textual: BracketStyle

    Bracket style for textual citations (:cite:t: and variations).

  bracket_year: BracketStyle

    Bracket style for year citations (:cite:year: and variations).

  person: PersonStyle

    Person style (applies to all relevant citation commands).

  post_text_sep: BaseText | str = ', '

    Separator between citation and post-text.

  pre_text_sep: BaseText | str = ' '

    Separator between pre-text and citation.

  text_reference_sep: BaseText | str = ' '

    Separator between text and reference for textual citations.