diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 0000000..9bf4fc6 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,30 @@ +name: Check Docs + +on: + pull_request: + branches: [main] + +jobs: + check: + name: Check Docs + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + + - name: Install Hatch + uses: pypa/hatch@install + + - name: Check docs type correctness + run: | + make docs-check + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + + - name: Render Docs + uses: quarto-dev/quarto-actions/render@v2 + with: + path: docs/ diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml new file mode 100644 index 0000000..207792e --- /dev/null +++ b/.github/workflows/docs-publish.yml @@ -0,0 +1,34 @@ +name: Publish Docs + +on: + push: + branches: [main] + +permissions: + contents: write + +jobs: + publish: + name: Publish Docs + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Install Hatch + uses: pypa/hatch@install + + - name: Check docs type correctness + run: | + make docs-check + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + + - name: Render Docs + uses: quarto-dev/quarto-actions/publish@v2 + with: + target: gh-pages + path: docs/ + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/Makefile b/Makefile index bd0219a..aa39d8c 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,9 @@ help : @echo ' make testall # <-- run tests in *all* python versions (uses hatch)' @echo ' make checkall # <-- check types in *all* python versions (uses hatch)' @echo + @echo ' make quarto-serve # <-- run quarto over the docs' + @echo ' make docs-check # <-- check types within the docs' + @echo test : hatch test -i python=3.8 -vv @@ -21,4 +24,18 @@ testall : checkall : hatch run types:check -.PHONY: help test check testall checkall +QUARTO_PATH := /usr/local/bin/quarto + +$(QUARTO_PATH) : + wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.7.31/quarto-1.7.31-linux-amd64.deb + sudo dpkg -i quarto-1.7.31-linux-amd64.deb + rm -f quarto-1.7.31-linux-amd64.deb + +quarto-serve : $(QUARTO_PATH) + rm -rf docs/_site/ docs/.quarto/ + $(QUARTO_PATH) preview docs + +docs-check : + hatch run docs:check + +.PHONY: help test check testall checkall quarto-serve docs-check diff --git a/README.md b/README.md index 7d8b239..67ae57a 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ ![Test Status](https://github.com/Rhobota/svs/actions/workflows/test.yml/badge.svg?branch=main) [![Downloads](https://static.pepy.tech/badge/svs)](https://pepy.tech/project/svs) +- 📚 **Official Docs:** [https://svs.rhobota.com/](https://svs.rhobota.com/) + - 🤔 What is SVS? - Semantic search via deep-learning vector embeddings. - A stupid-simple library for storing and retrieving your documents. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..4c23a06 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +/.quarto/ +_site/ diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..4294b3e --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +svs.rhobota.com diff --git a/docs/_quarto.yml b/docs/_quarto.yml new file mode 100644 index 0000000..7914ce1 --- /dev/null +++ b/docs/_quarto.yml @@ -0,0 +1,45 @@ +project: + type: website + preview: + port: 7777 + +website: + title: "SVS: Documentation" + favicon: "assets/SVS - Logo - Square - SMOOSHED.png" + open-graph: true + repo-url: https://github.com/Rhobota/svs + repo-subdir: "docs" + repo-actions: [edit, source, issue] + reader-mode: false + page-navigation: true + back-to-top-navigation: false + announcement: + icon: emoji-smile # https://icons.getbootstrap.com/ + content: "You found SVS!" + position: below-navbar + dismissable: false + navbar: + logo: "assets/SVS - Logo - Square - SMOOSHED.png" + background: primary + search: true + left: + - text: "Quickstart" + href: quickstart.ipynb + - about.qmd + right: + - icon: github + href: https://github.com/Rhobota/svs + target: _blank + sidebar: + style: "docked" + contents: auto + page-footer: + center: "Copyright © 2025 (MIT License)" + +format: + html: + theme: + - cosmo + - brand + css: styles.css + toc: true diff --git a/docs/about.qmd b/docs/about.qmd new file mode 100644 index 0000000..f7b22f4 --- /dev/null +++ b/docs/about.qmd @@ -0,0 +1,6 @@ +--- +title: "About" +order: 999 +--- + +About this site (TODO) diff --git a/docs/assets/SVS - Logo - Square - SMOOSHED.png b/docs/assets/SVS - Logo - Square - SMOOSHED.png new file mode 100644 index 0000000..86a4a4f Binary files /dev/null and b/docs/assets/SVS - Logo - Square - SMOOSHED.png differ diff --git a/docs/index.qmd b/docs/index.qmd new file mode 100644 index 0000000..8b3407c --- /dev/null +++ b/docs/index.qmd @@ -0,0 +1,7 @@ +--- +title: "SVS: Documentation" +--- + +This is the homepage. + +TODO diff --git a/docs/quickstart.ipynb b/docs/quickstart.ipynb new file mode 100644 index 0000000..0d25118 --- /dev/null +++ b/docs/quickstart.ipynb @@ -0,0 +1,111 @@ +{ + "cells": [ + { + "cell_type": "raw", + "id": "52fd1d52-ea95-449e-85f3-03bcec576bfe", + "metadata": {}, + "source": [ + "---\n", + "title: \"Quickstart with SVS\"\n", + "order: 010\n", + "---" + ] + }, + { + "cell_type": "markdown", + "id": "3fd21b1c-5bb1-4ebc-a90a-a36298d37fe7", + "metadata": {}, + "source": [ + "## Installing" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f8747c67-4a6e-43e4-bba6-7cb6acde649b", + "metadata": { + "scrolled": true + }, + "outputs": [], + "source": [ + "!pip install svs" + ] + }, + { + "cell_type": "markdown", + "id": "816cca77-d72a-44e7-ad6a-d320eed7cd79", + "metadata": {}, + "source": [ + "### Check your version!" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "a2e8014f-f470-4dee-b766-00a94cdb30df", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0.7.4\n" + ] + } + ], + "source": [ + "import svs\n", + "\n", + "print(svs.__version__)" + ] + }, + { + "cell_type": "markdown", + "id": "c1e8b087-a689-4df7-bdc6-19f3f965f8e8", + "metadata": {}, + "source": [ + "### Hello SVS" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "8458890f-abde-4413-a8f2-60ee63c18894", + "metadata": {}, + "outputs": [], + "source": [ + "from svs import KB\n", + "# TODO" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b628cae3-96c2-4ca5-b02f-1c7d2237dd00", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/styles.css b/docs/styles.css new file mode 100644 index 0000000..2ddf50c --- /dev/null +++ b/docs/styles.css @@ -0,0 +1 @@ +/* css styles */ diff --git a/pyproject.toml b/pyproject.toml index 768afe8..b69cb81 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,7 +44,7 @@ dependencies = [ ] [project.urls] -Documentation = "https://github.com/Rhobota/svs#readme" +Documentation = "https://svs.rhobota.com/" Issues = "https://github.com/Rhobota/svs/issues" Source = "https://github.com/Rhobota/svs" @@ -53,6 +53,7 @@ dev = [ "mypy>=1.10.0", "pytest>=8.1.1", "pytest-asyncio>=0.23.6", + "nbqa", ] [tool.hatch.build.targets.wheel] @@ -74,6 +75,13 @@ python = ["3.8", "3.9", "3.10", "3.11", "3.12"] [tool.hatch.envs.types.scripts] check = "mypy --install-types --non-interactive {args:src/svs tests examples}" +[tool.hatch.envs.docs] +python = "3.12" +features = ["dev"] + +[tool.hatch.envs.docs.scripts] +check = "nbqa mypy --install-types --non-interactive docs/" + [tool.hatch.envs.hatch-test] features = ["dev"] diff --git a/src/svs/__init__.py b/src/svs/__init__.py index 347820b..fe23471 100644 --- a/src/svs/__init__.py +++ b/src/svs/__init__.py @@ -21,4 +21,4 @@ 'make_ollama_embeddings_func', ] -__version__ = "0.7.3" +__version__ = "0.7.4" diff --git a/src/svs/kb.py b/src/svs/kb.py index 4d8e7bc..4486aff 100644 --- a/src/svs/kb.py +++ b/src/svs/kb.py @@ -1475,7 +1475,9 @@ def _get_embeddings_as_bytes( list_of_strings: List[str], ) -> List[bytes]: func = self._get_embedding_func() - list_of_list_of_floats = asyncio.run_coroutine_threadsafe(func(list_of_strings), self.loop).result() + awaitable = func(list_of_strings) + assert asyncio.iscoroutine(awaitable) + list_of_list_of_floats = asyncio.run_coroutine_threadsafe(awaitable, self.loop).result() return [ embedding_to_bytes(embedding) for embedding in list_of_list_of_floats @@ -1612,7 +1614,9 @@ def retrieve( assert self.db is not None embeddings_matrix, emb_id_lookup = self.embeddings_matrix.get_sync(self.db) func = self._get_embedding_func() - query_list_floats = asyncio.run_coroutine_threadsafe(func([query]), self.loop).result()[0] + awaitable = func([query]) + assert asyncio.iscoroutine(awaitable) + query_list_floats = asyncio.run_coroutine_threadsafe(awaitable, self.loop).result()[0] query_vec = np.array(query_list_floats, dtype=np.float32) _LOG.info("got embedding for query!") def superheavy() -> List[Tuple[float, int]]: