0
# Core Theme Setup
1

2
Main Sphinx extension setup and theme path functionality. This module provides the primary entry points for registering the sphinx-book-theme with Sphinx applications.
3

4
## Capabilities
5

6
### Theme Registration
7

8
The main setup function that registers the theme with Sphinx, adds assets, configures event handlers, and sets up all theme functionality.
9

10
```python { .api }
11
def setup(app: Sphinx) -> dict:
12
    """
13
    Register the sphinx-book-theme with a Sphinx application.
14
    
15
    This function:
16
    - Registers the HTML theme
17
    - Adds JavaScript and CSS files
18
    - Sets up message catalog for internationalization
19
    - Connects event handlers for page processing
20
    - Registers custom nodes and directives
21
    - Configures post-transforms
22
    
23
    Parameters:
24
    - app: Sphinx application instance
25
    
26
    Returns:
27
    dict with extension metadata including parallel read/write safety
28
    """
29
```
30

31
### Theme Path Resolution
32

33
Gets the filesystem path to the theme's HTML templates and static assets.
34

35
```python { .api }
36
def get_html_theme_path() -> Path:
37
    """
38
    Return the path to the HTML theme directory.
39
    
40
    Returns:
41
    Path to the theme directory containing templates and static assets
42
    """
43
```
44

45
### Module Constants
46

47
```python { .api }
48
__version__: str = "1.1.4"  # Package version
49
SPHINX_LOGGER: Logger  # Logger instance for theme messages
50
DEFAULT_LOG_TYPE: str = "sphinxbooktheme"  # Default log type
51
MESSAGE_CATALOG_NAME: str = "booktheme"  # Internationalization catalog name
52
```
53

54
## Usage Examples
55

56
### Basic Theme Registration
57

58
```python
59
from sphinx.application import Sphinx
60
import sphinx_book_theme
61

62
# Create Sphinx application
63
app = Sphinx(...)
64

65
# Register the theme
66
result = sphinx_book_theme.setup(app)
67
# Returns: {"parallel_read_safe": True, "parallel_write_safe": True}
68
```
69

70
### Getting Theme Assets Path
71

72
```python
73
from sphinx_book_theme import get_html_theme_path
74

75
# Get path to theme directory
76
theme_path = get_html_theme_path()
77
print(theme_path)  # /path/to/sphinx_book_theme/theme/sphinx_book_theme
78

79
# Access static assets
80
static_path = theme_path / "static"
81
templates_path = theme_path / "components"
82
```
83

84
### Version Information
85

86
```python
87
import sphinx_book_theme
88

89
print(f"Theme version: {sphinx_book_theme.__version__}")
90
# Output: Theme version: 1.1.4
91
```