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 or not 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.