Docs Framework

.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/

.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 }}

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

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.

docs/.gitignore

@@ -0,0 +1,2 @@
+/.quarto/
+_site/

docs/CNAME

@@ -0,0 +1 @@
+svs.rhobota.com

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 <strong>SVS</strong>!"
+    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 (<a href=\"https://github.com/Rhobota/svs/blob/main/LICENSE.txt\">MIT License</a>)"
+
+format:
+  html:
+    theme:
+      - cosmo
+      - brand
+    css: styles.css
+    toc: true

docs/about.qmd

@@ -0,0 +1,6 @@
+---
+title: "About"
+order: 999
+---
+
+About this site (TODO)

docs/index.qmd

@@ -0,0 +1,7 @@
+---
+title: "SVS: Documentation"
+---
+
+This is the homepage.
+
+TODO

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
+}

docs/styles.css

@@ -0,0 +1 @@
+/* css styles */

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"]
 

src/svs/__init__.py

@@ -21,4 +21,4 @@
     'make_ollama_embeddings_func',
 ]
 
-__version__ = "0.7.3"
+__version__ = "0.7.4"

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]]: