{"id":9254,"library":"python-docs-theme","title":"Python Docs Theme","description":"The Sphinx theme for the CPython docs and related projects. It provides a clean, responsive design and includes features like a dark mode, code copy buttons, and internationalization support. The library is actively maintained with frequent releases, typically on a monthly or bi-monthly cadence. The current version is 2026.3.","status":"active","version":"2026.3","language":"en","source_language":"en","source_url":"https://github.com/python/python-docs-theme/","tags":["Sphinx","documentation","theme","CPython"],"install":[{"cmd":"pip install python-docs-theme","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python interpreter version for the package.","package":"python","optional":false},{"reason":"The theme is built for Sphinx documentation projects.","package":"Sphinx","optional":false}],"imports":[{"note":"This setting is placed in your Sphinx project's conf.py file to activate the theme.","symbol":"html_theme","correct":"html_theme = 'python_docs_theme'"}],"quickstart":{"code":"mkdir my_docs\ncd my_docs\nsphinx-quickstart  # Follow prompts, choose 'y' for separate source/build, 'y' for autodoc\n\n# Edit source/conf.py (or conf.py directly if not using separate source/build)\n# Add or modify the following line:\n# html_theme = 'python_docs_theme'\n\n# Create a simple reStructuredText file (e.g., source/index.rst)\n# .. toctree::\n#    :maxdepth: 2\n#    :caption: Contents:\n#\n#    intro\n\n# Create source/intro.rst\n# My First Page\n# ============\n#\n# Hello, world! This is my first page using the Python Docs Theme.\n\nmake html  # or sphinx-build -b html source build\n","lang":"bash","description":"A basic Sphinx project setup, demonstrating how to enable the `python-docs-theme`. After running `sphinx-quickstart` to create your project structure, edit `conf.py` to set the `html_theme`."},"warnings":[{"fix":"Upgrade your Python environment to 3.12 or newer, or pin `python-docs-theme<2025.4`.","message":"Version 2025.4 and newer dropped support for Python 3.10 and 3.11.","severity":"breaking","affected_versions":">=2025.4"},{"fix":"Upgrade your Sphinx installation to 7.3 or newer, or pin `python-docs-theme<2025.4`.","message":"Version 2025.4 and newer requires Sphinx 7.3 or newer.","severity":"breaking","affected_versions":">=2025.4"},{"fix":"Upgrade to `python-docs-theme` 2026.2 or newer to ensure full copy button functionality for all code blocks, including shell and console examples.","message":"The behavior of code block copy buttons was enhanced across versions. Initially, they appeared on hover/click (2025.5), then specifically enabled for shell sessions and consoles (2026.2).","severity":"gotcha","affected_versions":"<2026.2"},{"fix":"If encountering unexpected layout issues, temporarily comment out or unset these theme-related configurations in `conf.py` to see if they are causing the conflict.","message":"Custom configurations for `html_sidebars`, `html_theme_path`, or `html_theme_config` in `conf.py` can interfere with the theme's default layout and features.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the theme is installed with `pip install python-docs-theme` and that `html_theme = 'python_docs_theme'` is correctly set in your `conf.py` file.","cause":"The `python-docs-theme` package is either not installed in the Sphinx build environment or `html_theme` is misspelled in `conf.py`.","error":"Theme error: no theme named 'python_docs_theme' found (missing theme.conf?)"},{"fix":"Upgrade your Python environment to 3.12 or a later version, or if unable to upgrade, pin the theme version to `python-docs-theme<2025.4`.","cause":"Attempting to build documentation with `python-docs-theme` version 2025.4 or newer using a Python interpreter older than 3.12.","error":"ValueError: The 'python-docs-theme' requires Python 3.12 or newer."},{"fix":"Upgrade your Sphinx installation to 7.3 or a later version using `pip install -U Sphinx`, or if unable to upgrade, pin the theme version to `python-docs-theme<2025.4`.","cause":"Attempting to build documentation with `python-docs-theme` version 2025.4 or newer using a Sphinx version older than 7.3.","error":"Theme error: The 'python-docs-theme' requires Sphinx 7.3 or newer."}]}