Development

Clone the repository:

git clone https://github.com/readthedocs/readthedocs-sphinx-search
cd readthedocs-sphinx-search/

Install dependencies via npm:

npm install

Generate minified JS and CSS files via Gulp:

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 http://127.0.0.1:8000 and start searching!

Note

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 https://readthedocs.org/api/v3/search/.

Releasing

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/__init__.py 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:

TWINE_USERNAME=__token__
TWINE_PASSWORD=<your-pypi-token>
make release
make tag

Note

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