feat(docs): Quarto-generated documentation site by lukeroantreeONS · Pull Request #96 · datasciencecampus/classifai

lukeroantreeONS · 2025-12-14T17:09:04Z

📌 Quarto-generated Documentation for the package

✨ Summary

This PR uses Quarto and Quartodoc to build a documentation website for the package, based on the package docstrings, as well as the markdown and notebook files.

Scope - this PR introduces only the requirements to generate the documentation site, and some updates to typehints / docstrings to facilitate forming the documentation.
A short follow-up PR will introduce the CICD YAML changes to build and deploy to GitHub Pages as part of the release workflow.

📜 Changes Introduced

feat: quarto-generated documentation site (overall)
feat: sidebar with sections for different components, and the demos
fix: make it consistently direct to the landing page (index.qmd) on opening
chore: make sidebar collapsed by default
ci: integrate into CICD pipeline, make / update github.io site

✅ Checklist

Please confirm you've completed these checks before requesting a review.

Code passes linting with Ruff
Security checks pass using Bandit
API and Unit tests are written and pass using pytest
Terraform files (if applicable) follow best practices and have been validated (terraform fmt & terraform validate)
DocStrings follow Google-style and are added as per Pylint recommendations
Documentation has been updated if needed

🔍 How to Test

Run uv sync to get the additional (dev) packages required
Run uv run quartodoc build to build the quarto markdown files
Run uv run quarto render to render html documentation site
Run uv run quarto preview to locally host the documentation site - explore it in a browser
Go to the proof-of-concept GitHub Pages site that I'm temporarily hosting on a fork, verify looks and behaves as the locally hosted one does.

Merge [strategy theirs] of main to bring up to date with latest codebase.

…boto) and backup font (system - Helvetica Neue)

frayle-ons

Really cool to see how the quarto docs work in terms of the yaml and styles. And nice work done on adding the documentation and some of the typing on arguments. Looks good overall, I've added a few questions and suggestions but I think most are just small things.

frayle-ons · 2026-02-23T16:07:44Z

src/classifai/indexers/__init__.py

@@ -1,4 +1,30 @@
-"""Indexers package."""
+# pylint: disable=C0301
+"""This module provides functionality for creating a vector index from a text file.


"from a csv (text) file" instead?

frayle-ons · 2026-02-23T16:10:16Z

src/classifai/indexers/__init__.py

+
+This class interacts with the Vectoriser class from the vectorisers submodule,
+expecting that any vector model used to generate embeddings used in the
+VectorStore objects is an instance of one of these classes, most notably


I would remove the hard reference to there being 3 Vectoriser classes. We might add more, users might make a custom one. Possibly it could refer to the base class instead

frayle-ons · 2026-02-23T16:12:49Z

src/classifai/indexers/__init__.py

Should this doctoring also capture the other functionalities of the VectorStore such as search() reverse_saerch(0 and embed(), and from_filesepace(). The key features and doctoring currently only refers to what happens in the index create / constructor step.

Good suggestions - I've updated this docstring in full (will push the updates shortly).
I've dropped the dependency information and usage description to keep the information more targeted towards the indexers module.

frayle-ons · 2026-02-23T16:21:24Z

src/classifai/indexers/main.py

 import shutil
 import time
 import uuid
+from typing import Optional, Self, Union  # noqa: F401


unused imports?

Good catch, thanks!

frayle-ons · 2026-02-23T16:23:44Z

src/classifai/indexers/main.py


        Returns:
-            VectorStore: An instance of the `VectorStore` class.
+            (VectorStore): An instance of the `VectorStore` class.


I think the parenthesis is not conventional style for writing docstrings - or is this needed for Quarto to work?

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

This was needed to get quartodoc to detect & render it as being a datatype rather than a variable name.

frayle-ons · 2026-02-23T16:26:56Z

src/classifai/servers/__init__.py

+an api-endpoint.

-from .main import get_router, run_server
+These functions interact with the ClassifAI PackageIndexer modules


should there be a space between Package and Indexer?

frayle-ons · 2026-02-23T16:27:48Z

src/classifai/servers/__init__.py

@@ -1,5 +1,12 @@
-"""FastAPI server as a package."""
+"""This module provides functionality for creating a start a restAPI service which
+allows a user to call the search methods of different VectorStore objects, from


'allows a user to call the search methods of one or more VectorStore objects'?

frayle-ons · 2026-02-23T16:41:17Z

src/classifai/indexers/dataclasses.py

Just checking were the TODO sections left intentionally?

I'd initially wanted to keep the scope of the PR to the quarto static site generation, but as these were the only ones missing I'm happy to add them to it.

frayle-ons · 2026-02-23T16:52:53Z

Final note that I could not get quarto to run locally using the how to test guide. Working on the current branch, I was able to uv sync, but then got the message quartodoc not found when trying to do quartodoc build. i had to run uv pip install quartodoc and tried uv add --dev quartodoc separately, both of which worked. However trying to resolve a similar issue with quarto render, I couldn't get this next line to run at all.

…lasses to website, updated docstrings as suggested, merged schema definitions directly into dataclasses

…o facilitate quarto rendering

lukeroantreeONS · 2026-02-24T23:09:30Z

Final note that I could not get quarto to run locally using the how to test guide. Working on the current branch, I was able to uv sync, but then got the message quartodoc not found when trying to do quartodoc build. i had to run uv pip install quartodoc and tried uv add --dev quartodoc separately, both of which worked. However trying to resolve a similar issue with quarto render, I couldn't get this next line to run at all.

Apologies for that, I did some of this work on a workstation, where I haveuv set up to directly configure an external virtual environment (so I can jump between uv- and poetry-provisioned projects); so I could use those commands 'directly'.

I'll update the testing instructions for the correct uv way of running them.

frayle-ons

Looks good to me, just one or two final suggestions after re-reviewing. I still couldn't get the local version of the docs to run as I was getting a ModuleNotFoundError: No module named 'griffe' when trying to run uv run quartodoc build but the temp deployed version looks good.

Can we add something to the GitHub readme page that links to the deployed quarto docs? I can't see anything at the moment in Github that points to new docs site. And can that somehow be hidden in the quarto rendered pages so it doesn't link to itself?

frayle-ons · 2026-03-02T10:05:58Z

src/classifai/indexers/dataclasses.py

+    and similarity scores.
+
+    This class represents the output of vector store search operations, containing
+    query information, matched documents, and similarity rankings.


and scores?

Thanks, addressed in latest commit

frayle-ons · 2026-03-02T10:08:41Z

src/classifai/indexers/main.py

+            batch_size (int): [optional] The batch size for processing the input file and batching to
            vectoriser. Defaults to 8.
-            meta_data (dict, optional): key,value pair metadata column names to extract from the input file and their types.
+            meta_data (dict): key,value pair metadata column names to extract from the input file and their types.


is this one no longer optional?

Thanks, I should have updated that to
(dict): [optional]

Addressed in latest commit 👍

lukeroantreeONS · 2026-03-02T11:24:48Z

Looks good to me, just one or two final suggestions after re-reviewing. I still couldn't get the local version of the docs to run as I was getting a ModuleNotFoundError: No module named 'griffe' when trying to run uv run quartodoc build but the temp deployed version looks good.

Thanks for the review, I'll implement the two changes you suggested. I'll check the griffe issue - that's a surprise as I don't think I needed to change anything for that when building & deploying the test GitHub Pages.

Can we add something to the GitHub readme page that links to the deployed quarto docs? I can't see anything at the moment in Github that points to new docs site.

Not at this point - I'll be submitting a follow-up PR to add the static site building & deployment to the CICD workflow, after which we can update the README to reference the GitHub Pages site. The one that's currently deployed is a throwaway one on my personal github pages, for testing / demo purposes.

And can that somehow be hidden in the quarto rendered pages so it doesn't link to itself?

That might be possible, but it wouldn't be straightforward / typical. I don't think having a self-referencing link to the documentation site in the landing page of the documentation site would be especially off-putting to people though.

lukeroantreeONS · 2026-03-02T11:52:28Z

Thanks for the review @frayle-ons - I've implemented the changes you recommended, and this is ready for re-review

frayle-ons

LGTM

feat(docs): WIP - quarto-generated documentation site

cf66cf8

lukeroantreeONS linked an issue Dec 14, 2025 that may be closed by this pull request

Set up MVP of Quarto documentation #95

Closed

lukeroantreeONS added 2 commits February 14, 2026 16:10

Merge branch 'main' into 95-set-up-mvp-of-quarto-documentation

be2837b

Merge [strategy theirs] of main to bring up to date with latest codebase.

chore(docs): update quarto docs to current repo version

a289123

lukeroantreeONS marked this pull request as ready for review February 15, 2026 11:48

lukeroantreeONS changed the title ~~feat(docs): WIP - quarto-generated documentation site~~ feat(docs): Quarto-generated documentation site Feb 15, 2026

github-actions bot added the enhancement New feature or request label Feb 15, 2026

lukeroantreeONS requested a review from frayle-ons February 17, 2026 11:15

chore(docs): update default web documentation font (Google Fonts - Ro…

3578ce4

…boto) and backup font (system - Helvetica Neue)

frayle-ons reviewed Feb 23, 2026

View reviewed changes

frayle-ons requested changes Feb 23, 2026

View reviewed changes

chore(docs): add missing docstrings, remove unused imports, add datac…

76302b8

…lasses to website, updated docstrings as suggested, merged schema definitions directly into dataclasses

lukeroantreeONS requested a review from a team as a code owner February 24, 2026 22:22

lukeroantreeONS requested a review from frayle-ons February 24, 2026 22:33

lukeroantreeONS added 2 commits February 24, 2026 22:53

Merge branch 'main' into 94-set-up-mvp-of-quarto-documentation

8eb3461

chore(docs): fixed italicisation ending and separated bullet points t…

2eafc03

…o facilitate quarto rendering

frayle-ons reviewed Mar 2, 2026

View reviewed changes

chore(quarto): refactor docstrings to separate type, optional

96e0333

lukeroantreeONS requested a review from frayle-ons March 2, 2026 11:52

frayle-ons approved these changes Mar 3, 2026

View reviewed changes

lukeroantreeONS merged commit 9f7435e into main Mar 3, 2026
5 checks passed

lukeroantreeONS deleted the 95-set-up-mvp-of-quarto-documentation branch March 3, 2026 21:53

Conversation

lukeroantreeONS commented Dec 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📌 Quarto-generated Documentation for the package

✨ Summary

📜 Changes Introduced

✅ Checklist

🔍 How to Test

Uh oh!

frayle-ons left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

frayle-ons commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lukeroantreeONS commented Feb 24, 2026

Uh oh!

frayle-ons left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukeroantreeONS commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lukeroantreeONS commented Mar 2, 2026

Uh oh!

frayle-ons left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lukeroantreeONS commented Dec 14, 2025 •

edited

Loading

frayle-ons left a comment •

edited

Loading

frayle-ons commented Feb 23, 2026 •

edited

Loading

lukeroantreeONS commented Mar 2, 2026 •

edited

Loading