{"id":2681,"library":"pydata-sphinx-theme","title":"PyData Sphinx Theme","description":"The PyData Sphinx Theme is a clean, three-column, Bootstrap-based Sphinx theme designed for the PyData community. It provides a modern, responsive design with built-in light/dark mode toggling and extensive customization options via `html_theme_options`. Currently at version 0.17.0, the project maintains a regular release cadence, with new versions published frequently (typically monthly or upon significant feature additions/bug fixes).","status":"active","version":"0.17.0","language":"en","source_language":"en","source_url":"https://github.com/pydata/pydata-sphinx-theme","tags":["sphinx","theme","documentation","pydata","bootstrap"],"install":[{"cmd":"pip install pydata-sphinx-theme","lang":"bash","label":"Install stable version"},{"cmd":"conda install pydata-sphinx-theme --channel conda-forge","lang":"bash","label":"Install with Conda"}],"dependencies":[{"reason":"Primary documentation generation framework. The theme aims to support the latest Sphinx version older than 6 months, but new major Sphinx releases may require a waiting period for full compatibility.","package":"Sphinx","optional":false}],"imports":[{"note":"The theme is configured in your Sphinx project's `conf.py` file by setting the `html_theme` variable. There are no direct Python imports from the library for typical usage.","symbol":"html_theme configuration","correct":"html_theme = \"pydata_sphinx_theme\""}],"quickstart":{"code":"# conf.py\nimport os\nimport sys\n\nproject = 'My Awesome Project'\ncopyright = '2026, My Team'\nauthor = 'My Team'\nrelease = '0.1'\n\nhtml_theme = \"pydata_sphinx_theme\"\n\nhtml_theme_options = {\n    \"icon_links\": [\n        {\n            \"name\": \"GitHub\",\n            \"url\": \"https://github.com/my-org/my-project\",\n            \"icon\": \"fa-brands fa-github\",\n            \"type\": \"fontawesome\",\n        }\n    ],\n    \"navbar_persistent\": [], # Remove 'search' from persistent navbar\n    \"show_prev_next\": False,\n    \"switcher\": {\n        \"version_match\": \"latest\",\n    },\n    \"footer_start\": [\"copyright\"],\n}\n\nhtml_static_path = ['_static']\nhtml_css_files = ['custom.css'] # Example for custom CSS","lang":"python","description":"To use the PyData Sphinx Theme, set `html_theme = \"pydata_sphinx_theme\"` in your `conf.py`. All theme-specific customizations are managed through the `html_theme_options` dictionary. This example also shows how to add an icon link and customize the footer."},"warnings":[{"fix":"If experiencing issues with a new Sphinx version, try pinning to an older, compatible Sphinx version (e.g., `pip install 'sphinx<6'`) or wait for a theme update. Refer to the theme's official documentation for supported Sphinx versions.","message":"New major versions of Sphinx may not be immediately supported. The PyData Sphinx Theme aims to support the latest Sphinx version that is older than 6 months. Using a very recent Sphinx release might lead to build issues until the theme is updated.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the theme's changelog for `v0.16.0` and subsequent releases. Update custom CSS and JavaScript to be compatible with Bootstrap 5 and vanilla JavaScript where jQuery was previously used. Some theme options might have been removed or renamed (e.g., `sidebarwidth` was removed in v0.16.1).","message":"Version 0.16.x introduced significant changes, including an upgrade to Bootstrap 5 and the removal of jQuery. This may break custom CSS, JavaScript, or certain theme options that relied on previous versions of Bootstrap (4) or jQuery.","severity":"breaking","affected_versions":">=0.16.0"},{"fix":"Always configure theme-specific settings through the `html_theme_options` dictionary. If you need to deeply customize aspects like sidebars, consult the theme's documentation for the correct approach rather than overriding global Sphinx `html_` variables directly.","message":"Theme-specific options must be set within the `html_theme_options` dictionary in `conf.py`. Directly defining `html_` variables (e.g., `html_sidebars`, `html_theme_path`, `html_theme_config`) might conflict with or override the theme's internal logic, leading to unexpected layout or functionality.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}