sphinx_typesense.config¶
Configuration handling for sphinx-typesense. This module manages all Typesense-related configuration values, including validation, defaults, and environment variable support.
Module Contents¶
Configuration handling for sphinx-typesense.
This module manages all Typesense-related configuration values in Sphinx’s conf.py, including validation, defaults, and environment variable support.
- Configuration Values:
- Required:
typesense_host: Typesense server hostname
typesense_port: Typesense server port
typesense_protocol: Connection protocol (http/https)
typesense_api_key: Admin API key for indexing
typesense_search_api_key: Search-only API key for frontend
- Optional:
typesense_collection_name: Name of the Typesense collection
typesense_doc_version: Documentation version tag
typesense_placeholder: Search input placeholder text
typesense_num_typos: Typo tolerance level (0-2)
typesense_per_page: Results per page
typesense_container: CSS selector for search container
typesense_filter_by: Default search filter
typesense_content_selectors: Theme content selectors
typesense_enable_indexing: Enable/disable indexing
typesense_drop_existing: Drop collection before reindex
Example
In conf.py:
import os
typesense_host = "localhost"
typesense_port = "8108"
typesense_protocol = "http"
typesense_api_key = os.environ.get("TYPESENSE_API_KEY", "")
typesense_search_api_key = os.environ.get("TYPESENSE_SEARCH_KEY", "")
- sphinx_typesense.config.get_effective_backend(config)[source]¶
Determine which backend to use based on configuration.
This function resolves the ‘auto’ backend setting to either ‘typesense’ or ‘pagefind’ based on the availability of API keys.
- Parameters:
config (Config) – The Sphinx configuration object.
- Returns:
‘typesense’ or ‘pagefind’ - the effective backend to use.
- Return type:
Note
When backend is ‘auto’: - Returns ‘typesense’ if an API key is present (config or environment) - Returns ‘pagefind’ if no API key is available
- sphinx_typesense.config.setup_config(app)[source]¶
Register Typesense configuration values with Sphinx.
- Parameters:
app (Sphinx) – The Sphinx application instance.
Note
Configuration values are registered with ‘html’ as their rebuild trigger, meaning changes will cause HTML rebuild.
- sphinx_typesense.config.validate_config(app, config)[source]¶
Validate Typesense configuration at build time.
This function performs comprehensive validation of all Typesense configuration values, with support for environment variable fallback for API keys.
- Parameters:
app (Sphinx) – The Sphinx application instance (unused but required by Sphinx event signature).
config (Config) – The Sphinx configuration object.
- Raises:
sphinx.errors.ConfigError – If required configuration is missing or invalid.
Note
API keys can be provided via environment variables (TYPESENSE_API_KEY, TYPESENSE_SEARCH_API_KEY) as fallback when not set in conf.py.
A warning is issued if admin and search API keys are identical, as this may indicate a security concern.
When typesense_enable_indexing is False, API keys are not required.
When typesense_backend is ‘pagefind’, Typesense API keys are not required.
When typesense_backend is ‘auto’ and no API keys are present, Pagefind will be used and API key validation is skipped.
Constants¶
Default Values¶
- sphinx_typesense.config.DEFAULT_COLLECTION_NAME: str = "sphinx_docs"¶
Default collection name for indexed documents.