0
# Sphinx Toolbox
1

2
Sphinx Toolbox is a comprehensive collection of Sphinx extensions providing enhanced documentation capabilities. It offers 50+ modular extensions that enhance the core Sphinx documentation generator with advanced features including GitHub integration, enhanced autodoc capabilities, LaTeX improvements, specialized directives, and modern Python type support.
3

4
## Package Information
5

6
- **Package Name**: sphinx-toolbox
7
- **Language**: Python
8
- **Installation**: `pip install sphinx-toolbox`
9

10
## Core Imports
11

12
```python
13
import sphinx_toolbox
14
```
15

16
For individual extensions:
17

18
```python
19
# Individual extension imports
20
from sphinx_toolbox import utils
21
from sphinx_toolbox import shields
22
from sphinx_toolbox.github import GitHubDomain
23
from sphinx_toolbox.more_autodoc import autoprotocol
24
```
25

26
## Basic Usage
27

28
Sphinx Toolbox is primarily used by adding extensions to your Sphinx `conf.py`:
29

30
```python
31
# Add the main extension (includes most sub-extensions)
32
extensions = [
33
    'sphinx_toolbox',
34
    # ... other extensions
35
]
36

37
# Or add individual extensions as needed
38
extensions = [
39
    'sphinx_toolbox.github',
40
    'sphinx_toolbox.shields',
41
    'sphinx_toolbox.more_autodoc.autoprotocol',
42
    'sphinx_toolbox.installation',
43
    # ... other extensions
44
]
45

46
# Configure GitHub integration (optional)
47
github_username = "your-username"
48
github_repository = "your-repo"
49
```
50

51
Example usage in reStructuredText documents:
52

53
```rst
54
.. installation:: package-name
55
   :pypi:
56
   :github: user/repo
57

58
.. shields:: 
59
   :pypi:
60
   :github:
61

62
.. confval:: my_config_value
63
   :type: str
64
   :default: "default value"
65
   
66
   Description of the configuration value.
67

68
:issue:`123` - Links to GitHub issue
69
:source:`path/to/file.py` - Links to source file
70
```
71

72
## Architecture
73

74
Sphinx Toolbox follows a modular architecture with these main components:
75

76
- **Core Extensions**: Individual Sphinx extensions that can be loaded separately
77
- **Utility Framework**: Common utilities (`utils`, `cache`, `config`) shared across extensions
78
- **Domain System**: Custom Sphinx domains (GitHub, LaTeX) with specialized roles and directives
79
- **Enhancement Layers**: Tweaks and improvements to existing Sphinx functionality
80
- **Setup Integration**: Coordinated setup system that manages extension dependencies and configuration
81

82
Each extension follows Sphinx's standard patterns with `setup()` functions returning `SphinxExtMetadata` for proper integration.
83

84
## Capabilities
85

86
### Core Utilities and Configuration
87

88
Essential utilities, caching, and configuration management used throughout the extension ecosystem.
89

90
```python { .api }
91
def setup(app: Sphinx) -> SphinxExtMetadata:
92
    """Main setup function that registers all sphinx-toolbox extensions."""
93
    
94
# Core utility functions
95
def make_github_url(username: str, repository: str) -> RequestsURL
96
def flag(argument: Any) -> bool
97
def code_repr(obj: Any) -> str
98
def parse_parameters(lines: List[str], tab_size: int = 8) -> List[Param]
99

100
# Configuration classes
101
class ToolboxConfig(Config):
102
    """Extended Config class with type annotations for sphinx-toolbox settings."""
103

104
# HTTP cache
105
cache: HTTPCache
106
```
107

108
[Core Utilities](./core-utilities.md)
109

110
### Content Creation Extensions
111

112
Enhanced directives for creating rich documentation content including code blocks, examples, installation instructions, shields, and collapsible sections.
113

114
```python { .api }
115
# Directives
116
class CodeBlock: ...  # Enhanced code-block with adjustable tab width
117
class CodeCell: ...   # Jupyter-style code cells
118
class InstallationDirective: ...  # Tabbed installation instructions
119
class CollapseDirective: ...      # Collapsible content sections
120
class reSTExampleDirective: ...   # Shows RST source and output
121

122
# Shield generation functions
123
def make_pypi_shield() -> str
124
def make_rtfd_shield() -> str
125
def make_github_shield() -> str
126
```
127

128
[Content Creation](./content-creation.md)
129

130
### GitHub Integration
131

132
Comprehensive GitHub integration with custom domain, roles for issues/PRs/users/repos, and API-powered features.
133

134
```python { .api }
135
class GitHubDomain(Domain):
136
    """Sphinx domain for GitHub.com integration."""
137

138
# GitHub roles
139
def issue_role() -> None  # :github:issue: role
140
def pull_role() -> None   # :github:pull: role  
141
def user_role() -> None   # :github:user: role
142
def repository_role() -> None  # :github:repo: role
143

144
# API functions
145
def get_issue_title(username: str, repository: str, issue_number: int) -> str
146
```
147

148
[GitHub Integration](./github-integration.md)
149

150
### Enhanced Autodoc
151

152
Modern Python feature documentation including Protocol, TypedDict, namedtuple, generics, and enhanced type hint processing.
153

154
```python { .api }
155
class ProtocolDocumenter(ClassDocumenter):
156
    """Autodocumenter for typing.Protocol classes."""
157

158
class TypedDictDocumenter(ClassDocumenter):
159
    """Autodocumenter for TypedDict classes."""
160

161
class NamedTupleDocumenter(ClassDocumenter):
162
    """Autodocumenter for namedtuple classes."""
163

164
class PrettyGenericAliasDocumenter(DataDocumenter):
165
    """Enhanced documentation for generic aliases."""
166
```
167

168
[Enhanced Autodoc](./enhanced-autodoc.md)
169

170
### Enhanced Autosummary
171

172
Improved automatic summary table generation with bug fixes, __all__ support, and customizable column widths.
173

174
```python { .api }
175
class PatchedAutosummary(Autosummary):
176
    """Enhanced autosummary directive with bug fixes."""
177

178
class PatchedAutoSummModuleDocumenter(ModuleDocumenter):
179
    """Module documenter with __all__ support."""
180

181
class AutosummaryWidths:
182
    """Configures autosummary table column widths."""
183

184
def get_documenter(app: Sphinx, obj: Any, parent: Any) -> Type[Documenter]
185
```
186

187
[Enhanced Autosummary](./enhanced-autosummary.md)
188

189
### LaTeX Support
190

191
Extensive LaTeX customization including custom directives, package management, layout improvements, and Unicode handling.
192

193
```python { .api }
194
class LaTeXDomain(Domain):
195
    """Domain for LaTeX-specific directives."""
196

197
class SamepageDirective: ...     # Keeps content on same page
198
class ClearPageDirective: ...    # Starts new page  
199
class VSpaceDirective: ...       # Adds vertical space
200

201
def use_package(package: str, config: Config, *args, **kwargs) -> None
202
def better_header_layout(config: Config, space_before: str, space_after: str) -> None
203
def replace_unknown_unicode(app: Sphinx, exception: Exception) -> None
204
```
205

206
[LaTeX Support](./latex-support.md)
207

208
### Configuration and Roles
209

210
Configuration value documentation, cross-referencing roles, and specialized formatting features.
211

212
```python { .api }
213
class ConfigurationValue(SphinxDirective):
214
    """Directive for documenting configuration values."""
215

216
# Roles
217
def asset_role() -> Tuple[List[Node], List[system_message]]  # :asset: role
218
def source_role() -> Tuple[List[Node], List[system_message]]  # :source: role
219
def wikipedia_role() -> Tuple[List[Node], List[system_message]]  # :wikipedia: role
220

221
# Cross-reference support
222
class PyDecoXRefRole(XRefRole):
223
    """Cross-references for Python decorators."""
224
```
225

226
[Configuration and Roles](./configuration-roles.md)
227

228
### Tweaks and Enhancements
229

230
Small but important improvements to Sphinx functionality including tab size handling, parameter formatting, footnote symbols, and compatibility fixes.
231

232
```python { .api }
233
# Tab size handling
234
def setup_tabsize_support(app: Sphinx) -> None
235

236
# Parameter formatting  
237
def format_param_dash() -> None
238

239
# Footnote improvements
240
class FootnoteSymbols: ...
241

242
# LaTeX layout improvements
243
def configure_latex_tweaks() -> None
244
```
245

246
[Tweaks and Enhancements](./tweaks-enhancements.md)
247

248
## Common Configuration Values
249

250
Sphinx Toolbox adds numerous configuration values to control its behavior:
251

252
```python
253
# GitHub integration
254
github_username = "username"
255
github_repository = "repository" 
256

257
# Asset handling
258
assets_dir = "_assets"
259

260
# Enhanced autodoc
261
all_typevars = True
262
no_unbound_typevars = False
263

264
# LaTeX customization  
265
latex_elements = {
266
    # Various LaTeX customizations applied automatically
267
}
268

269
# Autosummary
270
autosummary_col_type = "p{0.5\\linewidth}"
271
autodocsumm_member_order = "bysource"
272
```
273

274
## Error Handling
275

276
Sphinx Toolbox provides several exception types for configuration and processing errors:
277

278
```python { .api }
279
class MissingOptionError(SphinxError):
280
    """Raised when required configuration option is missing."""
281

282
class InvalidOptionError(SphinxError):  
283
    """Raised when configuration option has invalid value."""
284

285
class NoMatchError(Exception):
286
    """Raised when no matching values are found."""
287
```
288

289
## Testing Support
290

291
Comprehensive testing framework for Sphinx extensions with HTML/LaTeX regression testing, fixtures, and development tools:
292

293
```python { .api }
294
class SphinxBuilder:
295
    """Builder for testing Sphinx extensions."""
296

297
class HTMLRegressionFixture:
298
    """HTML regression testing utilities."""
299

300
class LaTeXRegressionFixture:
301
    """LaTeX regression testing utilities."""
302

303
def run_setup(app: Sphinx) -> None
304
def check_asset_copy() -> None
305
def remove_html_footer() -> None
306
def check_html_regression(test_output: str, expected_output: str) -> None
307
```
308

309
[Testing Utilities](./testing-utilities.md)