Sphinx Book Theme

Warnings

• gotcha The Sphinx Book Theme project is currently in 'maintenance mode'. This means new feature development is unlikely, and bug fixes may be slower or depend on community contributions. Users should manage expectations for active development.
  Fix: Be aware of the project's status and consider contributing if urgent fixes or features are needed.
• breaking The v1.0.0 release introduced a 'major refactor' of the theme's HTML structure and updated its base, PyData Sphinx Theme. Projects with existing custom CSS or HTML templates from pre-1.0 versions may require significant re-configuration and adjustments to maintain their appearance and functionality.
  Fix: Thoroughly review your custom CSS and HTML templates against the new theme structure. Consult the official changelog and migration guides if available.
• gotcha As 'sphinx-book-theme' heavily depends on 'pydata-sphinx-theme', updates to the parent theme can introduce unexpected style changes or require adjustments to `html_theme_options`. Specifically, versions 1.1.3 and 1.1.4 noted 'breaking style changes in pydata-sphinx-theme'.
  Fix: After upgrading, always rebuild and review your documentation for any visual regressions. Be prepared to update `html_theme_options` or custom CSS.
• gotcha A historical issue (Issue #496) reported that `sphinx-book-theme.css` was sometimes imported twice, which could prevent user-defined custom CSS from correctly overriding theme styles due to load order problems. While potentially fixed, users attempting deep CSS customization should be vigilant.
  Fix: If experiencing issues with CSS overrides, check the generated HTML for duplicate CSS imports. Consider using more specific selectors or `!important` as a last resort, or investigate the theme's CSS build process.

Install

• pip install sphinx-book-theme Install with pip

Imports

• html_theme

  html_theme = "sphinx_book_theme"

  To activate the theme, set 'html_theme' in your project's conf.py file. This is not a Python import in the traditional sense, but a configuration setting.

Quickstart

To quickly set up documentation with Sphinx Book Theme, first initialize a Sphinx project using `sphinx-quickstart`. Then, install the theme via pip. The core step involves modifying your `conf.py` file to set `html_theme = "sphinx_book_theme"` and optionally configure `html_theme_options` for features like a repository link. Finally, build your documentation using `make html` or `sphinx-build`.

# 1. Create a new Sphinx project (if you don't have one)
sphinx-quickstart

# 2. Install the theme
pip install sphinx-book-theme

# 3. Edit conf.py in your Sphinx project's source directory
#    Add 'sphinx_book_theme' to the html_theme variable:
#    html_theme = "sphinx_book_theme"
#    Optionally, add theme options, e.g., for a GitHub button:
#    html_theme_options = {
#        "repository_url": "https://github.com/executablebooks/sphinx-book-theme",
#        "use_repository_button": True,
#        "path_to_docs": "docs", # relative path to docs root from repo root
#        "home_page_in_toc": True,
#    }

# 4. Create an index.rst (or .md if using MyST-parser) and other content files
#    Example index.rst:
#    ====================
#    Welcome to My Book!
#    ====================
#
#    .. toctree::
#       :hidden:
#       :maxdepth: 2
#       :caption: Contents
#
#       page1
#       page2

# 5. Build your documentation
make html # or sphinx-build -M html . _build