sphinx_typesense.themes¶

Theme-specific selectors and configuration. This module provides content selectors and search bar placement logic for various Sphinx themes, enabling automatic detection and proper integration.

Module Contents¶

Theme-specific selectors and configuration for sphinx-typesense.

This module provides content selectors and search bar placement logic for various Sphinx themes, enabling automatic detection and proper integration without manual configuration.

Supported Themes:

sphinx_rtd_theme (ReadTheDocs)
furo
alabaster
pydata_sphinx_theme
sphinx_book_theme
shibuya

Usage:

Theme detection is automatic based on the configured html_theme. Custom selectors can override defaults via typesense_content_selectors.

Example

Override selectors in conf.py:

typesense_content_selectors = [
    ".my-custom-content",
    "article.main",
]

class sphinx_typesense.themes.ThemeConfig[source]¶

Bases: object

Configuration for a specific Sphinx theme.

name¶

Theme package name (e.g., “sphinx_rtd_theme”).

Type:: str

content_selectors¶

CSS selectors for main content area.

Type:: tuple[str, …]

search_container_selectors¶

CSS selectors for search bar placement.

Type:: tuple[str, …]

search_input_selector¶

CSS selector for existing search input.

Type:: str | None

name: str¶

content_selectors: tuple[str, ...]¶

search_container_selectors: tuple[str, ...]¶

search_input_selector: str | None = None¶

__init__(name, content_selectors, search_container_selectors, search_input_selector=None)¶

sphinx_typesense.themes.get_content_selectors(theme_name=None, custom_selectors=None)[source]¶

Get content selectors for a theme with optional custom overrides.

Returns custom selectors if provided, otherwise theme-specific selectors if the theme is recognized, otherwise the default fallback selectors.

Parameters:

theme_name (str | None) – The Sphinx theme name (e.g., “furo”, “sphinx_rtd_theme”).
custom_selectors (Sequence[str] | None) – User-provided custom CSS selectors to use instead of theme defaults.

Returns:

List of CSS selectors in priority order for extracting main content.

Return type:

list[str]

Example

>>> get_content_selectors("furo")
['article[role=main]', '.content']
>>> get_content_selectors("furo", [".my-content"])
['.my-content']
>>> get_content_selectors("unknown_theme")
['article[role=main]', 'main', '.body', '.document', '[role=main]']

sphinx_typesense.themes.get_search_placement(theme_name=None)[source]¶

Get the CSS selector for search bar placement.

Returns the appropriate CSS selector for where to place the Typesense search bar based on the detected theme.

Parameters:: theme_name (str | None) – The Sphinx theme name (e.g., “furo”, “sphinx_rtd_theme”).
Returns:: CSS selector string for search bar container placement.
Return type:: str

Example

>>> get_search_placement("sphinx_rtd_theme")
'.wy-side-nav-search'
>>> get_search_placement("unknown_theme")
'#typesense-search'

sphinx_typesense.themes.get_theme_config(app)[source]¶

Get theme configuration for the current Sphinx build.

Detects the configured HTML theme and returns the appropriate ThemeConfig with all selectors and settings.

Parameters:: app (Sphinx) – The Sphinx application instance.
Returns:: ThemeConfig for the detected theme, or a default config.
Return type:: ThemeConfig

sphinx_typesense.themes.get_content_selectors_for_app(app)[source]¶

Get content selectors for the current Sphinx application.

Returns user-configured selectors if set, otherwise theme-specific or default selectors.

Parameters:: app (Sphinx) – The Sphinx application instance.
Returns:: List of CSS selectors in priority order.
Return type:: list[str]

sphinx_typesense.themes.get_search_container_selector(app)[source]¶

Get the best selector for search container placement.

Parameters:: app (Sphinx) – The Sphinx application instance.
Returns:: CSS selector for search container placement.
Return type:: str

sphinx_typesense.themes.should_replace_search(app)[source]¶

Determine if the default search should be replaced.

Some themes may benefit from replacing their search input entirely, while others work better with an additional search.

Parameters:: app (Sphinx) – The Sphinx application instance.
Returns:: True if default search should be replaced.
Return type:: bool

ThemeConfig Class¶

The ThemeConfig is a frozen dataclass containing configuration for a specific Sphinx theme with these attributes:

name: Theme package name
content_selectors: CSS selectors for main content area
search_container_selectors: CSS selectors for search bar placement
search_input_selector: CSS selector for existing search input

Constants Reference¶

Theme Registries¶

THEME_SELECTORS provides CSS selectors for extracting main content from each supported theme. Listed in priority order (first match wins).

Supported themes:

sphinx_rtd_theme
furo
alabaster
pydata_sphinx_theme
sphinx_book_theme

SEARCH_PLACEMENT_SELECTORS provides CSS selectors for where to inject the search bar in each theme.

THEME_CONFIGS contains complete theme configurations with all details including content selectors, search container selectors, and search input selectors.

Default Fallbacks¶

DEFAULT_CONTENT_SELECTORS provides fallback selectors used when theme is not recognized:

article[role=main]
main
.body
.document
[role=main]

DEFAULT_SEARCH_PLACEMENT is #typesense-search by default.

DEFAULT_SEARCH_CONTAINER_SELECTORS includes:

#typesense-search
.search
.searchbox

Function Examples¶

Content Selectors¶

>>> from sphinx_typesense.themes import get_content_selectors
>>> get_content_selectors("furo")
['article[role=main]', '.content']

>>> get_content_selectors("furo", [".my-content"])
['.my-content']

>>> get_content_selectors("unknown_theme")
['article[role=main]', 'main', '.body', '.document', '[role=main]']

Search Placement¶

>>> from sphinx_typesense.themes import get_search_placement
>>> get_search_placement("sphinx_rtd_theme")
'.wy-side-nav-search'

>>> get_search_placement("unknown_theme")
'#typesense-search'

Adding New Themes¶

To add support for a new theme, add entries to the module constants:

# In sphinx_typesense/themes.py

THEME_SELECTORS["my_theme"] = [
    ".my-content-area",
    "main.content",
]

SEARCH_PLACEMENT_SELECTORS["my_theme"] = ".my-search-container"

THEME_CONFIGS["my_theme"] = ThemeConfig(
    name="my_theme",
    content_selectors=(".my-content-area", "main.content"),
    search_container_selectors=(".my-search-container",),
    search_input_selector='input[type="search"]',
)