{"library":"sphinx-rtd-theme","title":"Read the Docs Sphinx Theme","description":"The `sphinx-rtd-theme` is the official Sphinx theme for Read the Docs, designed to provide an excellent reading experience for documentation users on both desktop and mobile devices. It is widely adopted across many open-source projects. The current version is 3.1.0, and it maintains an active development and release cadence.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/readthedocs/sphinx_rtd_theme","tags":["Sphinx","theme","documentation","Read the Docs"],"install":[{"cmd":"pip install sphinx-rtd-theme","lang":"bash","label":"Install `sphinx-rtd-theme`"}],"dependencies":[{"reason":"Required for building documentation. Version 3.1.0 of sphinx-rtd-theme supports Sphinx >=6.0.","package":"Sphinx","optional":false},{"reason":"Core dependency for reStructuredText parsing in Sphinx. Version constraints align with supported Sphinx versions.","package":"docutils","optional":false},{"reason":"Required for interactive features like search, smooth scrolling, and the flyout menu when using the theme as an extension.","package":"sphinxcontrib-jquery","optional":false}],"imports":[{"note":"This setting should be placed in your Sphinx project's conf.py file to activate the theme.","symbol":"html_theme","correct":"html_theme = \"sphinx_rtd_theme\""}],"quickstart":{"code":"# First, create a Sphinx project if you don't have one:\n# sphinx-quickstart\n\n# In your project's conf.py file:\n# ------------------------------\n# import os\n# import sys\n# sys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Awesome Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\nrelease = '0.1.0'\n\nextensions = [\n    'sphinx_rtd_theme'\n]\n\nhtml_theme = \"sphinx_rtd_theme\"\n\n# To build the documentation (run from your project root):\n# -------------------------------------------------------\n# make html\n# or\n# sphinx-build -b html . _build","lang":"python","description":"After installing the theme, update your Sphinx project's `conf.py` file to specify `sphinx_rtd_theme` as the `html_theme` and add `sphinx_rtd_theme` to your `extensions` list. Then, build your Sphinx documentation."},"warnings":[{"fix":"Upgrade Sphinx to 6.0 or newer and Python to 3.8 or newer. If not possible, pin `sphinx-rtd-theme<2.0.0` or `sphinx-rtd-theme<3.1.0` depending on your Sphinx/Python versions.","message":"Version 3.1.0 (and 2.0.0 onwards) drops support for Sphinx versions older than 6.0. Projects using older Sphinx versions will need to upgrade Sphinx or pin an older `sphinx-rtd-theme` version. Similarly, Python versions older than 3.8 are no longer supported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Sphinx project uses the HTML5 writer. Modern Sphinx versions use HTML5 by default.","message":"The HTML4 writer is officially deprecated since version 2.0.0 and will throw an error if still configured.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove `analytics_id` and `analytics_anonymize_ip` from `conf.py` and configure `sphinxcontrib-googleanalytics` instead.","message":"The `analytics_id` and `analytics_anonymize_ip` configuration options are deprecated in version 3.1.0. Users should migrate to `sphinxcontrib-googleanalytics` for Google Analytics integration.","severity":"deprecated","affected_versions":">=3.1.0"},{"fix":"Remove `html_theme_path` from `conf.py` if it points to the installed theme. Migrate custom CSS to be included differently as per theme documentation.","message":"Defining `html_theme_path` will raise a warning in newer versions of the theme, as it's no longer required for local installations. `extra_css_files` is also deprecated and will be removed in a future version.","severity":"deprecated","affected_versions":">=3.1.0"},{"fix":"Add `'sphinx_rtd_theme'` to your `extensions` list in `conf.py`.","message":"For search, smooth scrolling, and the flyout menu to function correctly, `sphinx_rtd_theme` must be explicitly declared in the `extensions` list in `conf.py`. This ensures `sphinxcontrib-jquery` is activated.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If encountering build errors after switching themes, try unsetting `html_sidebars`, `html_theme_path`, or `html_theme_config` in your `conf.py`.","message":"Errors during documentation builds with a new theme are often due to conflicting theme-specific configurations such as `html_sidebars`, `html_theme_path`, or `html_theme_config`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}