Build System Integration

class WebpackBuildCommand(distutils.cmd.Command):
    """
    Generate static assets via webpack production build.
    
    Command: python setup.py build_assets
    
    Actions:
    - Runs npm install to ensure dependencies
    - Executes webpack production build via webpack.prod.js
    - Skips build in CI and TOX environments
    
    Environment Detection:
    - Skips if 'CI' environment variable is set
    - Skips if 'TOX_ENV_NAME' environment variable is set
    """

# Build production assets
python setup.py build_assets

# Equivalent npm command
npm run build

class WebpackDevelopCommand(distutils.cmd.Command):
    """
    Run webpack development server with live reloading.
    
    Command: python setup.py watch
    
    Actions:
    - Starts webpack-dev-server with hot module replacement
    - Opens browser automatically
    - Uses webpack.dev.js configuration
    - Provides live reloading for development
    """

# Start development server
python setup.py watch

# Equivalent npm command  
npm run dev

class UpdateTranslationsCommand(distutils.cmd.Command):
    """
    Run complete localization workflow.
    
    Command: python setup.py update_translations
    
    Sub-commands (executed in order):
    1. extract_messages - Extract translatable strings
    2. update_catalog - Update existing translation files
    3. transifex - Push/pull translations from Transifex
    4. compile_catalog - Compile .po files to .mo files
    """

class TransifexCommand(distutils.cmd.Command):
    """
    Update translation files through Transifex service.
    
    Command: python setup.py transifex
    
    Actions:
    - Pushes source strings to Transifex (tx push --source)
    - Pulls reviewed translations (tx pull --mode onlyreviewed -f -a)
    
    Requirements:
    - transifex-client package installed
    - Transifex project configured
    """

{
  "scripts": {
    "dev": "webpack-dev-server --open --config webpack.dev.js"
  }
}

{
  "scripts": {
    "build": "webpack --config webpack.prod.js"
  }
}

{
  "scripts": {
    "preinstall": "bin/preinstall.js"
  }
}

// Development-specific webpack settings
module.exports = {
  mode: 'development',
  devtool: 'eval-source-map',
  devServer: {
    contentBase: './sphinx_rtd_theme/static',
    hot: true,
    open: true
  },
  // SCSS compilation with source maps
  // Live reloading for template changes
  // Unminified output for debugging
}

// Production-specific webpack settings  
module.exports = {
  mode: 'production',
  optimization: {
    minimizer: [
      new OptimizeCSSAssetsPlugin(),
      new UglifyJsPlugin()
    ]
  },
  // SCSS compilation and minification
  // Asset optimization and compression
  // File fingerprinting for cache busting
}

// Shared webpack configuration
module.exports = {
  entry: './src/theme.js',
  output: {
    path: path.resolve(__dirname, 'sphinx_rtd_theme/static'),
    filename: 'js/theme.js'
  },
  module: {
    rules: [
      // SCSS processing
      // JavaScript compilation  
      // Font and image handling
      // CSS extraction
    ]
  }
}

// Source structure
src/
├── theme.js          // Main JavaScript entry point
├── sass/            // SCSS stylesheets  
│   ├── theme.scss   // Main stylesheet
│   └── _*.scss      // Partials and components
└── fonts/           // Font assets

// Output structure in sphinx_rtd_theme/static/
static/
├── css/
│   ├── theme.css    // Compiled and minified CSS
│   └── fonts/       // Web font files
└── js/
    └── theme.js     // Compiled and minified JavaScript

{
  "devDependencies": {
    "webpack": "^4.46.0",
    "webpack-cli": "^3.3.12", 
    "webpack-dev-server": "^3.11.2",
    "webpack-merge": "^4.2.1",
    "node-sass": "^4.14.1",
    "sass-loader": "^7.3.0",
    "css-loader": "^3.6.0",
    "mini-css-extract-plugin": "^0.6.0",
    "optimize-css-assets-webpack-plugin": "^5.0.4",
    "font-awesome": "^4.7.0",
    "jquery": "^3.6.0"
  }
}

# setup.cfg [options.extras_require]
dev = [
    "transifex-client",  # Translation management
    "bump2version",      # Version bumping
    "wheel",            # Package building
    "twine"             # Package publishing
]

# babel.cfg - Translation extraction configuration
[python: **.py]
[jinja2: **/templates/**.html]
encoding = utf-8

# setup.cfg - Babel extraction settings
[extract_messages]
mapping_file = babel.cfg
output_file = sphinx_rtd_theme/locale/sphinx.pot
keywords = _ l_ lazy_gettext
add_comments = Translators:

# setup.cfg - Translation catalog settings
[update_catalog]
domain = sphinx
input_file = sphinx_rtd_theme/locale/sphinx.pot
output_dir = sphinx_rtd_theme/locale/

[compile_catalog]
domain = sphinx
directory = sphinx_rtd_theme/locale/

# Set up development environment
npm install
pip install -e .[dev]

# Start development server
python setup.py watch
# OR
npm run dev

# Build production assets
python setup.py build_assets
# OR  
npm run build

# Extract translatable strings
python setup.py extract_messages

# Update translation files
python setup.py update_catalog

# Sync with Transifex
python setup.py transifex

# Compile translations
python setup.py compile_catalog

# Complete translation workflow
python setup.py update_translations

# In CI environment (NODE_ENV=production, CI=true)
# Assets are built automatically during package installation
pip install sphinx-rtd-theme

# Manual asset building disabled in CI
python setup.py build_assets  # Skipped due to CI environment

# Custom setup.py extension
from sphinx_rtd_theme.setup import WebpackBuildCommand

class CustomBuildCommand(WebpackBuildCommand):
    def run(self):
        # Custom pre-build steps
        super().run()
        # Custom post-build steps
        
setup(
    cmdclass={
        'build_assets': CustomBuildCommand,
    }
)

# setup.cfg - Package data inclusion
[options.package_data]
sphinx_rtd_theme = [
    "theme.conf",
    "*.html", 
    "static/css/*.css",
    "static/css/fonts/*.*",
    "static/js/*.js"
]

# Include additional files in source distribution
include *.rst *.txt *.yml *.yaml *.json
include babel.cfg
include webpack*.js
recursive-include sphinx_rtd_theme/locale *.po *.pot
recursive-include src *.js *.scss