Contributing guide

Thank you for being interested in contributing to the sphinx-book-theme! You are awesome ✨.

This project follows the Executable Books Project contribution guidelines. It contains information about our conventions around coding style, pull request workflow, commit messages and more.

The rest of these sections contain information about developing the sphinx-book-theme specifically.

Contributing Guide

• Set up your development workflow
  • Set up your development environment
  • Build the documentation
  • Update the theme’s assets (CSS/JS)
  • Auto-build the docs when you make changes
  • Run the tests
  • The {example} directive
• Architecture of the repository
  • src/sphinx_book_theme/ - Theme source files
  • docs/ - Site documentation
  • webpack.config.js and package.json - Webpack and dependencies
  • tests/ - Testing infrastructure
  • .github/workflows/ - Continuous Integration and Deployment
  • Parent theme - pydata-sphinx-theme
• Style and design
  • Design principles and inspiration
  • SCSS build process
  • CSS/SCSS naming conventions
  • SCSS folder structure
• Testing infrastructure
  • Run the tests with a single environment
  • List all test environments
  • Supply arguments to pytest
  • Re-build an environment from scratch
  • Test audits with lighthouse
  • Test multiple Sphinx versions
• Releases and version numbers
  • Release strategy
  • Version numbers
• Translation workflow
  • Structure of translation files
  • Workflow of translations
  • To update a translation
• Creating sub-themes
  • Hashing your assets
  • Defining your own CSS