PyData Sphinx Theme

PyData Sphinx Theme is a clean, three-column, Bootstrap-based theme for Sphinx documentation, created by and for the PyData community. It gives Python projects a modern documentation site with a top navigation bar, in-page and site-wide sidebars, light and dark modes, and responsive layouts out of the box.

Used by many scientific Python projects, the theme emphasizes readability and navigation for large documentation sets. It offers extensive configuration for headers, footers, version switchers, announcement banners, and branding, letting teams ship a polished docs experience without writing custom HTML or CSS.

What You Get

• A responsive, three-column documentation layout with top navbar and sidebars
• Built-in light and dark mode with a user toggle
• Configurable headers, footers, version switchers, and announcement banners
• Bootstrap-based components and Pygments styling for readable code blocks
• Localization support and extensive html_theme_options for branding

Common Use Cases

• Building a modern documentation site for a Python library or framework
• Standardizing docs styling across a family of scientific Python projects
• Adding dark mode and version switching to existing Sphinx docs
• Customizing navigation and branding without hand-writing templates

Under The Hood

Architecture - The Python package under src/pydata_sphinx_theme registers the theme and a set of Sphinx event hooks. Modules like toctree.py build navigation, logo.py and edit_this_page.py inject branding and source links, pygments.py wires syntax highlighting, and translator.py plus locale/ handle internationalized rendering. The visual layer lives in the theme/ HTML templates and an assets/ pipeline of SCSS and JavaScript.

Tech Stack - A mix of Python (about 42%), SCSS (32%), JavaScript (14%), and HTML (12%). It builds on Sphinx and Bootstrap, compiles styles from SCSS, and ships bundled JS for the navbar, search, and theme toggle. Packaging targets PyPI and conda-forge.

Code Quality - The project is actively maintained by a large contributor base (150+), with frequent releases and CI on GitHub Actions plus Read the Docs builds. Python helpers are modular and single-purpose, and the SCSS/JS assets are organized under a dedicated build pipeline.

API Design - There is almost no code to write: set html_theme to pydata_sphinx_theme in conf.py and configure behavior declaratively through html_theme_options. The wide, well-documented option set covers navigation, branding, and layout, keeping customization approachable for documentation authors.