0
# Build System Integration
1

2
Asset compilation and translation management system with webpack integration, custom setup.py commands, and npm script integration for theme development and distribution.
3

4
## Python Build Commands
5

6
Custom distutils commands available via `python setup.py <command>` for theme development and asset management.
7

8
### WebpackBuildCommand
9

10
```python { .api }
11
class WebpackBuildCommand(distutils.cmd.Command):
12
    """
13
    Generate static assets via webpack production build.
14
    
15
    Command: python setup.py build_assets
16
    
17
    Actions:
18
    - Runs npm install to ensure dependencies
19
    - Executes webpack production build via webpack.prod.js
20
    - Skips build in CI and TOX environments
21
    
22
    Environment Detection:
23
    - Skips if 'CI' environment variable is set
24
    - Skips if 'TOX_ENV_NAME' environment variable is set
25
    """
26
```
27

28
**Usage:**
29

30
```bash
31
# Build production assets
32
python setup.py build_assets
33

34
# Equivalent npm command
35
npm run build
36
```
37

38
### WebpackDevelopCommand
39

40
```python { .api }
41
class WebpackDevelopCommand(distutils.cmd.Command):
42
    """
43
    Run webpack development server with live reloading.
44
    
45
    Command: python setup.py watch
46
    
47
    Actions:
48
    - Starts webpack-dev-server with hot module replacement
49
    - Opens browser automatically
50
    - Uses webpack.dev.js configuration
51
    - Provides live reloading for development
52
    """
53
```
54

55
**Usage:**
56

57
```bash
58
# Start development server
59
python setup.py watch
60

61
# Equivalent npm command  
62
npm run dev
63
```
64

65
### Translation Management
66

67
#### UpdateTranslationsCommand
68

69
```python { .api }
70
class UpdateTranslationsCommand(distutils.cmd.Command):
71
    """
72
    Run complete localization workflow.
73
    
74
    Command: python setup.py update_translations
75
    
76
    Sub-commands (executed in order):
77
    1. extract_messages - Extract translatable strings
78
    2. update_catalog - Update existing translation files
79
    3. transifex - Push/pull translations from Transifex
80
    4. compile_catalog - Compile .po files to .mo files
81
    """
82
```
83

84
#### TransifexCommand
85

86
```python { .api }
87
class TransifexCommand(distutils.cmd.Command):
88
    """
89
    Update translation files through Transifex service.
90
    
91
    Command: python setup.py transifex
92
    
93
    Actions:
94
    - Pushes source strings to Transifex (tx push --source)
95
    - Pulls reviewed translations (tx pull --mode onlyreviewed -f -a)
96
    
97
    Requirements:
98
    - transifex-client package installed
99
    - Transifex project configured
100
    """
101
```
102

103
## NPM Scripts Integration
104

105
Package.json scripts for frontend development workflow:
106

107
### Development Script
108

109
```json { .api }
110
{
111
  "scripts": {
112
    "dev": "webpack-dev-server --open --config webpack.dev.js"
113
  }
114
}
115
```
116

117
Starts development server with:
118
- Live reloading for SCSS/JS changes
119
- Automatic browser opening
120
- Hot module replacement
121
- Source maps for debugging
122

123
### Production Build Script
124

125
```json { .api }
126
{
127
  "scripts": {
128
    "build": "webpack --config webpack.prod.js"
129
  }
130
}
131
```
132

133
Creates optimized production assets:
134
- Minified CSS and JavaScript
135
- Optimized images and fonts
136
- Asset fingerprinting for caching
137
- Compressed file sizes
138

139
### Pre-installation Script
140

141
```json { .api }
142
{
143
  "scripts": {
144
    "preinstall": "bin/preinstall.js"
145
  }
146
}
147
```
148

149
Runs automatically before npm install to handle environment-specific setup requirements.
150

151
## Webpack Configuration
152

153
### Development Configuration (webpack.dev.js)
154

155
```javascript { .api }
156
// Development-specific webpack settings
157
module.exports = {
158
  mode: 'development',
159
  devtool: 'eval-source-map',
160
  devServer: {
161
    contentBase: './sphinx_rtd_theme/static',
162
    hot: true,
163
    open: true
164
  },
165
  // SCSS compilation with source maps
166
  // Live reloading for template changes
167
  // Unminified output for debugging
168
}
169
```
170

171
### Production Configuration (webpack.prod.js)
172

173
```javascript { .api }
174
// Production-specific webpack settings  
175
module.exports = {
176
  mode: 'production',
177
  optimization: {
178
    minimizer: [
179
      new OptimizeCSSAssetsPlugin(),
180
      new UglifyJsPlugin()
181
    ]
182
  },
183
  // SCSS compilation and minification
184
  // Asset optimization and compression
185
  // File fingerprinting for cache busting
186
}
187
```
188

189
### Common Configuration (webpack.common.js)
190

191
```javascript { .api }
192
// Shared webpack configuration
193
module.exports = {
194
  entry: './src/theme.js',
195
  output: {
196
    path: path.resolve(__dirname, 'sphinx_rtd_theme/static'),
197
    filename: 'js/theme.js'
198
  },
199
  module: {
200
    rules: [
201
      // SCSS processing
202
      // JavaScript compilation  
203
      // Font and image handling
204
      // CSS extraction
205
    ]
206
  }
207
}
208
```
209

210
## Asset Pipeline
211

212
### Source Files
213

214
```javascript { .api }
215
// Source structure
216
src/
217
├── theme.js          // Main JavaScript entry point
218
├── sass/            // SCSS stylesheets  
219
│   ├── theme.scss   // Main stylesheet
220
│   └── _*.scss      // Partials and components
221
└── fonts/           // Font assets
222
```
223

224
### Compiled Output
225

226
```javascript { .api }
227
// Output structure in sphinx_rtd_theme/static/
228
static/
229
├── css/
230
│   ├── theme.css    // Compiled and minified CSS
231
│   └── fonts/       // Web font files
232
└── js/
233
    └── theme.js     // Compiled and minified JavaScript
234
```
235

236
## Build Dependencies
237

238
### NPM Development Dependencies
239

240
```json { .api }
241
{
242
  "devDependencies": {
243
    "webpack": "^4.46.0",
244
    "webpack-cli": "^3.3.12", 
245
    "webpack-dev-server": "^3.11.2",
246
    "webpack-merge": "^4.2.1",
247
    "node-sass": "^4.14.1",
248
    "sass-loader": "^7.3.0",
249
    "css-loader": "^3.6.0",
250
    "mini-css-extract-plugin": "^0.6.0",
251
    "optimize-css-assets-webpack-plugin": "^5.0.4",
252
    "font-awesome": "^4.7.0",
253
    "jquery": "^3.6.0"
254
  }
255
}
256
```
257

258
### Python Development Dependencies
259

260
```python { .api }
261
# setup.cfg [options.extras_require]
262
dev = [
263
    "transifex-client",  # Translation management
264
    "bump2version",      # Version bumping
265
    "wheel",            # Package building
266
    "twine"             # Package publishing
267
]
268
```
269

270
## Translation Workflow
271

272
### Babel Configuration
273

274
```ini { .api }
275
# babel.cfg - Translation extraction configuration
276
[python: **.py]
277
[jinja2: **/templates/**.html]
278
encoding = utf-8
279
```
280

281
### Message Extraction
282

283
```ini { .api }
284
# setup.cfg - Babel extraction settings
285
[extract_messages]
286
mapping_file = babel.cfg
287
output_file = sphinx_rtd_theme/locale/sphinx.pot
288
keywords = _ l_ lazy_gettext
289
add_comments = Translators:
290
```
291

292
### Catalog Management
293

294
```ini { .api }
295
# setup.cfg - Translation catalog settings
296
[update_catalog]
297
domain = sphinx
298
input_file = sphinx_rtd_theme/locale/sphinx.pot
299
output_dir = sphinx_rtd_theme/locale/
300

301
[compile_catalog]
302
domain = sphinx
303
directory = sphinx_rtd_theme/locale/
304
```
305

306
## Usage Examples
307

308
### Development Workflow
309

310
```bash
311
# Set up development environment
312
npm install
313
pip install -e .[dev]
314

315
# Start development server
316
python setup.py watch
317
# OR
318
npm run dev
319

320
# Build production assets
321
python setup.py build_assets
322
# OR  
323
npm run build
324
```
325

326
### Translation Management
327

328
```bash
329
# Extract translatable strings
330
python setup.py extract_messages
331

332
# Update translation files
333
python setup.py update_catalog
334

335
# Sync with Transifex
336
python setup.py transifex
337

338
# Compile translations
339
python setup.py compile_catalog
340

341
# Complete translation workflow
342
python setup.py update_translations
343
```
344

345
### CI/CD Integration
346

347
```bash
348
# In CI environment (NODE_ENV=production, CI=true)
349
# Assets are built automatically during package installation
350
pip install sphinx-rtd-theme
351

352
# Manual asset building disabled in CI
353
python setup.py build_assets  # Skipped due to CI environment
354
```
355

356
### Custom Build Integration
357

358
```python
359
# Custom setup.py extension
360
from sphinx_rtd_theme.setup import WebpackBuildCommand
361

362
class CustomBuildCommand(WebpackBuildCommand):
363
    def run(self):
364
        # Custom pre-build steps
365
        super().run()
366
        # Custom post-build steps
367
        
368
setup(
369
    cmdclass={
370
        'build_assets': CustomBuildCommand,
371
    }
372
)
373
```
374

375
## Package Distribution
376

377
### Static Asset Inclusion
378

379
```ini { .api }
380
# setup.cfg - Package data inclusion
381
[options.package_data]
382
sphinx_rtd_theme = [
383
    "theme.conf",
384
    "*.html", 
385
    "static/css/*.css",
386
    "static/css/fonts/*.*",
387
    "static/js/*.js"
388
]
389
```
390

391
### MANIFEST.in
392

393
```ini { .api }
394
# Include additional files in source distribution
395
include *.rst *.txt *.yml *.yaml *.json
396
include babel.cfg
397
include webpack*.js
398
recursive-include sphinx_rtd_theme/locale *.po *.pot
399
recursive-include src *.js *.scss
400
```