sphinx-sql-backend

SQL backend for the Sphinx documentation generator.

What's inside

A Sphinx extension to provide Full-Text-Search (FTS) based on SQL databases.

The package is completely based on atsphinx-sqlite3fts by Kazuya Takei, so many kudos and thanks go out to him. See also sqlite3fts on GitHub.

Status

Please note that the sphinx-sql-backend package contains alpha-, beta- and incubation-quality code, and as such, is considered to be a work in progress. Contributions of all kinds are much welcome, in order to make it more solid, and to add features.

Breaking changes should be expected until a 1.0 release, so version pinning is strongly recommended, especially when you use it as a library.

How it works

• Indexing: When running sphinx-build, store documents into database.
• Searching: Provide backend service for responding to search requests and search-as-you-type UI based on readthedocs-sphinx-search.

Installation

pip install git+https://github.com/panodata/sphinx-sql-backend.git

Usage

1. Register extension into your conf.py and configure it.

extensions = [
    #
    # Other extensions
    #
    "atsphinx.sqlite3fts",  # Add it
]

2. Run builder (html-based builder only).

sphinx-build -M html source build

3. To try it in local, use http.server module.

python -m http.server -d _build/html

Please access http://localhost:8000/search.html

Development

Install package in development mode:

pip install --editable='.[cli,docs,test]' --prefer-binary

Start PostgreSQL server:

docker run --rm -it --publish=5432:5432 --env "POSTGRES_HOST_AUTH_METHOD=trust" postgres:16 postgres -c log_statement=all

Invoke software tests:

export POSTGRES_LOG_STATEMENT=all
pytest -vvv

Invoke linters:

pip install pre-commit
pre-commit run --all-files