Metadata-Version: 2.1
Name: sphinx-docsearch
Version: 0.1.0
Summary: A Sphinx extension for replacing the built-in search with Algolia DocSearch
License: MIT
Author: Algolia
Author-email: support@algolia.com
Requires-Python: >=3.8,<4.0
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Dist: sphinx (<7.2) ; python_version >= "3.8" and python_version < "3.9"
Requires-Dist: sphinx (>=7.2,<7.5) ; python_version >= "3.9" and python_version < "3.10"
Requires-Dist: sphinx (>=8,<9) ; python_version >= "3.10"
Description-Content-Type: text/markdown

# Algolia DocSearch for Sphinx

This extension for the [Sphinx](https://www.sphinx-doc.org/en/master/) documentation generator
replaces Sphinx's built-in search with Algolia DocSearch.

## Before you begin

[**Apply for DocSearch**](https://docsearch.algolia.com/apply).
You'll get an email with your Algolia credentials.

This extension supports Python versions 3.8 and later and Sphinx versions 5 and later.

For a list of supported themes, see [HTML theme support](https://sphinx-docsearch.readthedocs.io/themes.html)

## Install

Install the `sphinx-docsearch` package:

```sh
pip install sphinx-docsearch
```

## Configure

1. Add `sphinx-docsearch` to your Sphinx configuration:

   ```python
   # conf.py
   extensions += ["sphinx_docsearch"]
   ```

1. Add your Algolia credentials to your Sphinx configuration:

   ```python
   # conf.py
   docsearch_app_id = "<DOCSEARCH_APP_ID>"
   docsearch_api_key = "<DOCSEARCH_SEARCH_API_KEY>"
   docsearch_index_name = "<DOCSEARCH_INDEX_NAME>"
   ```

   See also:

   - [Manage credentials](https://sphinx-docsearch.readthedocs.io/credentials.html)
   - [Configure DocSearch](https://sphinx-docsearch.readthedocs.io/configuration.html)

## Customize

To change what the crawler should extract from your pages,
see [Record Extractor](https://docsearch.algolia.com/docs/record-extractor).

If you're using a Sphinx theme that's not supported,
you can add custom templates to add the DocSearch UI.
You can further customize the look of the DocSearch UI by adding custom CSS.
For more information, see [Customize](https://sphinx-docsearch.readthedocs.io/customization.html).

