Skip to content

SQL backend for the Sphinx documentation generator. The focus is fulltext search (FTS), but there may be more. [WIP]

License

Notifications You must be signed in to change notification settings

panodata/sphinx-sql-backend

Repository files navigation

sphinx-sql-backend

SQL backend for the Sphinx documentation generator.

Run CI Documentation Status

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
]
  1. Run builder (html-based builder only).
sphinx-build -M html source build
  1. 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