or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bibliography-processing.mdcitation-system.mdconfiguration.mdfootnote-citations.mdindex.mdnodes-transforms.mdstyle-system.md
tile.json

tessl/pypi-sphinxcontrib-bibtex

Sphinx extension for BibTeX style citations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/sphinxcontrib-bibtex@2.6.x

To install, run

npx @tessl/cli install tessl/pypi-sphinxcontrib-bibtex@2.6.0

index.mddocs/

Sphinxcontrib Bibtex

A Sphinx extension that enables BibTeX-style citation support for Sphinx documentation projects. It allows developers to insert bibliographic citations into their documentation using BibTeX files through bibliography directives and citation roles, similar to LaTeX's citation system.

Package Information

  • Package Name: sphinxcontrib-bibtex
  • Package Type: Sphinx extension
  • Language: Python
  • Installation: pip install sphinxcontrib-bibtex

Core Imports

# Main extension setup function
from sphinxcontrib.bibtex import setup

# Core classes for advanced usage (not typically needed by end users)
from sphinxcontrib.bibtex.domain import BibtexDomain, Citation
from sphinxcontrib.bibtex.directives import BibliographyDirective, BibliographyKey, BibliographyValue
from sphinxcontrib.bibtex.roles import CiteRole
from sphinxcontrib.bibtex.foot_roles import FootCiteRole
from sphinxcontrib.bibtex.bibfile import BibData, BibFile
from sphinxcontrib.bibtex.citation_target import CitationTarget
from sphinxcontrib.bibtex.nodes import bibliography, raw_latex
from sphinxcontrib.bibtex.transforms import BibliographyTransform, node_text_transform

Basic Usage

Extension Configuration

Add to your Sphinx conf.py:

extensions = ['sphinxcontrib.bibtex']
bibtex_bibfiles = ['refs.bib']

Citation Usage in Documents

See :cite:t:`1987:nelson` for an introduction to non-standard analysis.
Non-standard analysis is fun :cite:p:`1987:nelson`.

.. bibliography::

With footnote citations:

See :footcite:t:`1987:nelson` for an introduction to non-standard analysis.
Non-standard analysis is fun\ :footcite:p:`1987:nelson`.

.. footbibliography::

Architecture

The extension follows Sphinx's domain-based architecture:

  • Domains: BibtexDomain manages global citations, BibtexFootDomain manages footnote citations
  • Directives: BibliographyDirective and FootBibliographyDirective process bibliography blocks
  • Roles: CiteRole and FootCiteRole process inline citations
  • Transforms: BibliographyTransform converts bibliography nodes to formatted citations
  • Style System: Pluggable referencing and formatting styles based on pybtex

Capabilities

Extension Setup and Configuration

Core extension setup function and configuration system that integrates with Sphinx's configuration framework.

def setup(app: Sphinx) -> Dict[str, Any]:
    """Set up the bibtex extension with Sphinx application."""

Configuration

Citation System

Regular citation system with global bibliography management across all documents in a project.

class BibtexDomain(Domain):
    """Sphinx domain for bibtex citations."""
    
class BibliographyDirective(Directive):
    """Processes the bibliography directive."""
    
class CiteRole(XRefRole):
    """Processes cite roles like :cite:p: and :cite:t:."""

Citation System

Footnote Citation System

Local footnote-based citations that are resolved per document, useful for per-document bibliographies.

class BibtexFootDomain(Domain):
    """Sphinx domain for footnote citations."""
    
class FootBibliographyDirective(Directive):
    """Processes the footbibliography directive."""
    
class FootCiteRole(SphinxRole):
    """Processes footcite roles like :footcite:p: and :footcite:t:."""

Footnote Citations

Bibliography File Processing

BibTeX file parsing, caching, and processing functionality built on pybtex.

class BibData(NamedTuple):
    """Information about collection of bib files."""
    encoding: str
    bibfiles: Dict[Path, BibFile]
    data: BibliographyData

def parse_bibdata(bibfilenames: List[Path], encoding: str) -> BibData:
    """Parse bibliography files with given encoding."""

def process_bibdata(bibdata: BibData, bibfilenames: List[Path], encoding: str) -> BibData:
    """Parse and cache bibliography data."""

Bibliography Processing

Style and Formatting System

Pluggable style system for citation formatting and referencing, supporting multiple citation styles.

class BaseReferenceStyle(ABC):
    """Base class for citation reference styles."""
    
def format_references(
    style: BaseReferenceStyle,
    role_name: str,
    references: Iterable[Tuple[Entry, FormattedEntry, ReferenceInfo]]
) -> BaseText:
    """Format references according to given style."""

Style System

Document Nodes and Transforms

Internal document tree nodes and transform classes for processing bibliography elements during Sphinx document generation.

class bibliography(nodes.General, nodes.Element):
    """Node for representing a bibliography in the document tree."""
    
class BibliographyTransform(SphinxPostTransform):
    """Transform to generate citation entries for bibliography nodes."""
    default_priority: int = 5
    
def node_text_transform(node: docutils.nodes.Element) -> None:
    """Apply extra text transformations to a document node."""

Nodes and Transforms

Types

class Citation(NamedTuple):
    """Information about a citation."""
    citation_id: str
    bibliography_key: BibliographyKey
    key: str
    entry: Entry
    formatted_entry: FormattedEntry
    tooltip_entry: Optional[FormattedEntry]

class CitationTarget(NamedTuple):
    """Citation key with pre-text and post-text."""
    key: str
    pre: str
    post: str

class BibliographyKey(NamedTuple):
    """Unique key for each bibliography directive."""
    docname: str
    id_: str

class BibFile(NamedTuple):
    """Information about a parsed bib file."""
    mtime: float
    keys: Dict[str, None]

class BibliographyValue(NamedTuple):
    """Information about a bibliography directive."""
    line: int
    bibfiles: List[Path]
    style: str
    list_: str
    enumtype: str
    start: int
    labelprefix: str
    keyprefix: str
    filter_: ast.AST
    citation_nodes: Dict[str, docutils.nodes.Element]
    keys: List[str]