tessl/pypi-sphinxcontrib-bibtex

Sphinx extension for BibTeX style citations.

Overview

Eval results

Files

Configuration

Name: tessl/pypi-sphinxcontrib-bibtex
Author: tessl

Extension setup and configuration system that integrates with Sphinx's configuration framework to customize citation behavior, styling, and file handling.

Capabilities

Extension Setup

Main extension setup function that registers all components with Sphinx and configures the extension.

def setup(app: Sphinx) -> Dict[str, Any]:
    """
    Set up the bibtex extension:
    
    - register config values
    - register directives
    - register nodes
    - register roles
    - register transforms
    - connect events to functions
    
    Parameters:
        app: Sphinx application instance
        
    Returns:
        Dict with extension metadata including version and parallel processing support
    """

Configuration Values

The extension registers these configuration values with Sphinx:

# Bibliography styling
bibtex_default_style: str = "alpha"  # Default pybtex bibliography style
bibtex_reference_style: str = "label"  # Citation reference style 
bibtex_foot_reference_style: str = "foot"  # Footnote citation reference style

# File handling
bibtex_bibfiles: List[str] = None  # Required: List of bibliography files
bibtex_encoding: str = "utf-8-sig"  # Encoding for bib files

# Display options  
bibtex_tooltips: bool = True  # Enable citation tooltips
bibtex_tooltips_style: str = ""  # Style for tooltips (empty uses default)

# Headers
bibtex_bibliography_header: str = ""  # Header for bibliography sections
bibtex_footbibliography_header: str = ""  # Header for footnote bibliography sections

# ID templates
bibtex_cite_id: str = ""  # Template for citation IDs
bibtex_footcite_id: str = ""  # Template for footnote citation IDs  
bibtex_bibliography_id: str = ""  # Template for bibliography IDs
bibtex_footbibliography_id: str = ""  # Template for footnote bibliography IDs

Usage Examples

Basic Configuration

# conf.py
extensions = ['sphinxcontrib.bibtex']
bibtex_bibfiles = ['refs.bib']

Advanced Configuration

# conf.py
extensions = ['sphinxcontrib.bibtex']

# Bibliography files
bibtex_bibfiles = ['references.bib', 'additional-refs.bib']
bibtex_encoding = 'utf-8'

# Styling
bibtex_default_style = 'plain'
bibtex_reference_style = 'author_year'
bibtex_foot_reference_style = 'foot'

# Display options
bibtex_tooltips = True
bibtex_tooltips_style = 'plain'

# Headers
bibtex_bibliography_header = '**References**'
bibtex_footbibliography_header = '**Document References**'

# Custom ID templates
bibtex_cite_id = 'cite-{key}'
bibtex_bibliography_id = 'bibliography-{bibliography_count}'

ID Template Variables

ID templates support these format variables:

{key}: The citation key
{bibliography_count}: Sequential bibliography number
{footbibliography_count}: Sequential footnote bibliography number

Example:

bibtex_cite_id = "ref-{bibliography_count}-{key}"  # Results in: ref-1-smith2020

Error Handling

The extension validates configuration and provides helpful error messages:

Missing bibtex_bibfiles: Raises ExtensionError if not configured
File not found: Logs warning if bibliography files cannot be found
Invalid styles: Falls back to defaults with warnings for unknown styles
Template errors: Provides warnings for malformed ID templates

Install with Tessl CLI

npx tessl i tessl/pypi-sphinxcontrib-bibtex

docs

bibliography-processing.md

citation-system.md

configuration.md

footnote-citations.md