0
# Configuration
1

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

4
## Capabilities
5

6
### Extension Setup
7

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

10
```python { .api }
11
def setup(app: Sphinx) -> Dict[str, Any]:
12
    """
13
    Set up the bibtex extension:
14
    
15
    - register config values
16
    - register directives
17
    - register nodes
18
    - register roles
19
    - register transforms
20
    - connect events to functions
21
    
22
    Parameters:
23
        app: Sphinx application instance
24
        
25
    Returns:
26
        Dict with extension metadata including version and parallel processing support
27
    """
28
```
29

30
### Configuration Values
31

32
The extension registers these configuration values with Sphinx:
33

34
```python { .api }
35
# Bibliography styling
36
bibtex_default_style: str = "alpha"  # Default pybtex bibliography style
37
bibtex_reference_style: str = "label"  # Citation reference style 
38
bibtex_foot_reference_style: str = "foot"  # Footnote citation reference style
39

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

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

48
# Headers
49
bibtex_bibliography_header: str = ""  # Header for bibliography sections
50
bibtex_footbibliography_header: str = ""  # Header for footnote bibliography sections
51

52
# ID templates
53
bibtex_cite_id: str = ""  # Template for citation IDs
54
bibtex_footcite_id: str = ""  # Template for footnote citation IDs  
55
bibtex_bibliography_id: str = ""  # Template for bibliography IDs
56
bibtex_footbibliography_id: str = ""  # Template for footnote bibliography IDs
57
```
58

59
### Usage Examples
60

61
#### Basic Configuration
62

63
```python
64
# conf.py
65
extensions = ['sphinxcontrib.bibtex']
66
bibtex_bibfiles = ['refs.bib']
67
```
68

69
#### Advanced Configuration
70

71
```python
72
# conf.py
73
extensions = ['sphinxcontrib.bibtex']
74

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

79
# Styling
80
bibtex_default_style = 'plain'
81
bibtex_reference_style = 'author_year'
82
bibtex_foot_reference_style = 'foot'
83

84
# Display options
85
bibtex_tooltips = True
86
bibtex_tooltips_style = 'plain'
87

88
# Headers
89
bibtex_bibliography_header = '**References**'
90
bibtex_footbibliography_header = '**Document References**'
91

92
# Custom ID templates
93
bibtex_cite_id = 'cite-{key}'
94
bibtex_bibliography_id = 'bibliography-{bibliography_count}'
95
```
96

97
#### ID Template Variables
98

99
ID templates support these format variables:
100

101
- `{key}`: The citation key
102
- `{bibliography_count}`: Sequential bibliography number
103
- `{footbibliography_count}`: Sequential footnote bibliography number
104

105
Example:
106
```python
107
bibtex_cite_id = "ref-{bibliography_count}-{key}"  # Results in: ref-1-smith2020
108
```
109

110
## Error Handling
111

112
The extension validates configuration and provides helpful error messages:
113

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