Clone the repository:

git clone
cd readthedocs-sphinx-search/

Install dependencies via npm:

npm install

Generate minified JS and CSS files via Gulp:


Run the test suite with tox. More information about testing is available at Testing page.

Local testing

You can test this extension from the docs folder:

cd docs
pip install sphinx-autobuild
pip install -r requirements.txt
sphinx-autobuild . _build/html

Go to and start searching!


The extension works when is hosted on Read the Docs, but to make it work locally a custom READTHEDOCS_DATA js variable is injected automatically to send the search requests to


Make sure you have the latest version of these packages:

python -m pip install --upgrade setuptools wheel twine build

Update the version in sphinx_search/ and package.json, and run:

npm run build
npm run changelog

Open a pull request with the changes. After the pull request is merged, run:

make release
make tag


Make sure you don’t have any uncommitted changes before releasing.