PyData Sphinx Theme

The pydata-sphinx-theme right-hand Table of Contents (TOC) behavior changes based on the number of top-level headers (headers using the = underline style) in your document:

1. Multiple top-level headers: If a page contains more than one top-level header, the TOC will include every top-level header as a primary entry. Subsequent sub-headers (using - or ~ underlines) will be nested under the top-level header they follow.

2. Single top-level header: If a page contains only one top-level header, the theme treats it as the page title. In this case, the TOC will not show the top-level header itself; instead, it will only display the headers that appear underneath it.

All configuration options for the PyData Sphinx Theme are passed through the html_theme_options dictionary in your Sphinx conf.py file. This dictionary uses key: val pairs to control the behavior, look, and feel of your site. Most theme-specific settings (such as branding, navigation, and UI elements) must be defined within this variable.

# Example configuration in conf.py
html_theme = 'pydata_sphinx_theme'

html_theme_options = {
    # Theme options go here
    'logo': {'text': 'My Project'},
    'show_guides': True,
}

The theme manages assets in two distinct locations depending on whether they are source files or compiled outputs:

• Source Files (SCSS/JS):
  • SCSS styles: src/pydata_sphinx_theme/assets/styles
  • JS scripts: src/pydata_sphinx_theme/assets/scripts (includes imports for vendored libraries like Bootstrap).
• Compiled Assets (Static):
  • Compiled CSS/JS: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static

Note: The compiled static folder is not tracked in Git but is included in the theme's final distribution.

The PyData Sphinx Theme follows a tiered merge policy designed to balance speed of iteration with code quality and stakeholder input. The policy categorizes changes into three types: moderate changes, major new features/breaking changes, and minor changes/bugfixes.

Key principles include:

• Prioritizing iterative improvement over perfection.
• Giving preference to the opinions of maintainers from the PyData ecosystem.
• Encouraging high-level discussion of important decisions before implementation.
• Assuming maintainers act in good faith.

The PyData Sphinx Theme includes specialized CSS/SCSS rules to ensure that documentation for PyData ecosystem packages looks consistent and readable in both light and dark modes. These styles are applied via two specific extension files located in src/pydata_sphinx_theme/assets/styles/:

1. extensions/_execution.scss: Contains styles for Sphinx libraries that execute code and insert output into the documentation (e.g., MyST-NB, Jupyter Sphinx, and the Matplotlib plot directive). This is the preferred location for generic improvements that benefit multiple packages.
2. extensions/_pydata.scss: Contains styles for specific library quirks. This should be used minimally for special-casing individual libraries in the PyData ecosystem.

To determine if a user has manually specified a configuration value in their conf.py (as opposed to a value being set by a default), check the app.config._raw_config attribute. This attribute contains only the values explicitly provided by the user.

Additionally, you can check app.config.overrides to see if a value was provided via the Sphinx Command Line Interface (CLI).

# Returns True if the user manually specified 'somekey' in conf.py
if "somekey" in app.config._raw_config:
    # user provided it
    pass

# Check for CLI overrides
if "somekey" in app.config.overrides:
    # user provided it via CLI
    pass