readthedocs-sphinx-search

0.3.2 verified Fri May 01 auth: no python

A Sphinx extension that adds autocomplete search-as-you-type functionality to documentation hosted on Read the Docs. Currently at version 0.3.2, updated infrequently. Requires Sphinx and works out of the box with Read the Docs hosting.

pip install readthedocs-sphinx-search

Common errors

error ImportError: cannot import name 'readthedocs_sphinx_search' ↓

cause The package is named with hyphens on PyPI but must be imported as a single underscore name.

fix

Use 'readthedocs_sphinx_search' (underscore) in extensions list.

error sphinx.errors.ExtensionError: Could not import extension readthedocs_sphinx_search (exception: No module named 'readthedocs_sphinx_search') ↓

cause The package may not be installed or the virtual environment is not activated.

fix

Run 'pip install readthedocs-sphinx-search' and ensure your Sphinx build uses the same Python environment.

error Search bar not appearing on the documentation site ↓

cause The extension requires the Read the Docs domain to work. Offline builds will not show the search bar.

fix

Build and deploy the docs on Read the Docs. For local testing, set the environment variable 'READTHEDOCS' to 'True' or configure 'rtds_search_endpoint'.

Warnings

gotcha This extension only works when your docs are hosted on Read the Docs. It does not work on other hosting platforms (e.g., GitHub Pages, Netlify) because it relies on Read the Docs' search API. ↓

fix Ensure your project is built and hosted on Read the Docs, or implement a custom search backend.

gotcha If using a custom theme, the search UI may not appear or may look broken. The extension adds a search bar that expects default Sphinx theme styles. ↓

fix Override the theme's search template or manually include the required CSS/JS assets.

deprecated The library has not seen updates since 2021. Future Sphinx versions may break compatibility. ↓

fix Consider using the built-in search support from Read the Docs Addons or monitor for updates.

Quickstart

Add 'readthedocs_sphinx_search' to the extensions list in your conf.py. No further configuration is required for projects hosted on Read the Docs.

extensions = [
    'readthedocs_sphinx_search',
]

# Optional: configure search endpoint if not on Read the Docs
# rtds_search_endpoint = 'https://your-project.readthedocs.io/api/v2/search/'