Registry / web-framework / readthedocs-sphinx-search

readthedocs-sphinx-search

library0.3.2pypypiunverified

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.

web-framework

pip install readthedocs-sphinx-search

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · READTHEDOCS-SPHINX

readthedocs-sphinx-search

web-frameworkpythonv0.3.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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/'

Debug

Known issues

gotchaThis 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.

affects: all

gotchaIf 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.

affects: all

deprecatedThe 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.

affects: >=0.3.2

Errors

Common errors & fixes

ImportError: cannot import name 'readthedocs_sphinx_search'

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.

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

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.

Search bar not appearing on the documentation site

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'.

Upgrade

Version history

0.3.2latest on PyPI · released Jan 15, 2024

Audit

Dependencies

sphinxrequiredRequired to build documentation.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/readthedocs/readthedocs-sphinx-search ↗

packagehttps://pypi.org/project/readthedocs-sphinx-search/ ↗

docshttps://readthedocs-sphinx-search.readthedocs.io/ ↗