atsphinx-sqlite3fts#

PyPI

 Published stable

GitHub Actions

 Run CI Status

Read the Docs

 Documentation Status

atsphinx-sqlite3fts is sphinx extension to provide some components.

  • Full-text search database by FTS5

  • Custom HTML to search by user

This is experimental package. It implements minimum works and provide only minimum configurations.

Getting started#

Requirements#

  • Python 3.7+

    • You can see requirement packages from pyproject.toml.

  • SQLite 3.34.0+

Installation#

This is published on PyPI.

pip install atsphinx-sqlite3fts

If you want to try latest source, install from GitHub.

pip install git+https://github.com/atsphinx/sqlite3fts.git

Usage#

At first, configuration on conf.py of your documentation.

extensions = [
    "atsphinx.sqlite3fts",
]

# Set if you want to use for HTML search
sqlite3fts_use_search_html = True

Try search by local database#

You can build database by sqlite builder.

make sqlite
sqlite3 _build/sqlite/db.sqlite

sqlite> SELECT * FROM content MATCH "installation";

See Database specification.

Configuration#

sqlite3fts_exclude_pages#
Type:

List[str]

Default:

[]

Example:

["index", "404"]

List of documents that are excluded for target of register database. This should be used when some documents need not be searched.

Value must be docname, not filename. If you want to exclude index.rst, you should set index.

sqlite3fts_use_search_html#
Type:

bool

Default:

False

Example:

True

Use custom search page.

If you set True for this, atsphinx-sqlite3fts does these.

  • Override JavaScript file for search.

  • Change style to display search results.

Database specification#

This is writing about specification of generated database.

Base#

Using SQLite and FTS5 extension. Details are described in SQLite website.

atsphinx-sqlite3fts run these strategy.

  • Use trigram tokenizer to search Japanese text (not work with unicode61).

  • Split document table and searching virtual table (document has page that is not target of search).

Tables#

atsphinx-sqlite3fts use peewee to manage database schemas.

document table#

This table contains all of property for refer to documents.

section table#

This table contains all of property for refer to section of documents.

content table#

This table is registered only targets of full-text searching. Currently, this contains title and body of documents.

body is plain text to pick all text contents from doctree.

Relation#

  • section.document_id is as foreign key to document.id.

  • document-fts.rowid is as foreign key to section.id.

You can use JOIN statement some tables.

Simple CLI tool#

atsphinx-sqlite3fts provides simple CLI tool to display result of searching.

Requirements#

If you want to use CLI tool, it need Click library. You can insallt atsphinx-sqlite3fts with extra packages.

pip install 'atsphinx-sqlite3fts[cli]'

Usage example#

Before run CLI, build database by sphinx-build.

sphinx-build -b sqlite . _build

To search from database, run command with path of database and keyword.

atsphinx-sqlite3fts _build/db.sqlite Hello

cli-tool
     Simple CLI tool

getting-started
     Getting started

Command display pagename and title.

Changelogs#

Latest changes#

v0.1.3#

date:

2023-10-26

(Not featured release)

Misc#

  • Fix to upload into GitHub Releases.

  • Fix release-date of v0.1.2

v0.1.2#

date:

2023-10-26

Important#

  • Rename from sphinx-sqlite3fts

Fixes#

  • Ref content-root when using Sphinx>=7.2

v0.1.1#

date:

2022-11-28

Small bug-fixes.

Fixes#

  • Force override searchindex.js as blank file.

  • searchtools.js initialize engine lazy.

v0.1.0#

date:

2022-11-27

For JavaScript based search-engine.

Features#

  • Split sections from document for search (useful for refs of page).

  • Add flag: search from database instead of Sphinx bundled search feature.

v0.0.3#

date:

2022-11-26

Update documents

Documentation#

  • Add badges into readme and documentation.

  • Follow notes for v0.0.2

v0.0.2#

date:

2022-11-23

Supporting for local development.

Miscellaneous#

  • Use bump2version for release.

  • Configure about line-length for pycodestyle.

v0.0.1#

date:

2022-11-23

This is first release.

Features#

  • Add sqlite builder that generate db.sqlite.

  • Inject generator for database into html based builder.