Add initial Vamana docstrings to Python (#386)

Author: jparismorgan

_quarto.yml

@@ -39,6 +39,7 @@ quartodoc:
         - index.Index
         - flat_index
         - ivf_flat_index
+        - vamana_index
         - ingestion
 
 website:

apis/python/src/tiledb/vector_search/vamana_index.py

@@ -1,3 +1,15 @@
+"""
+Vamana Index implementation.
+
+Vamana is based on Microsoft's DiskANN vector search library, as described in these papers:
+```
+  Subramanya, Suhas Jayaram, and Rohan Kadekodi. DiskANN: Fast Accurate Billion-Point Nearest Neighbor Search on a Single Node.
+
+  Singh, Aditi, et al. FreshDiskANN: A Fast and Accurate Graph-Based ANN Index for Streaming Similarity Search. arXiv:2105.09613, arXiv, 20 May 2021, http://arxiv.org/abs/2105.09613.
+
+  Gollapudi, Siddharth, et al. “Filtered-DiskANN: Graph Algorithms for Approximate Nearest Neighbor Search with Filters.” Proceedings of the ACM Web Conference 2023, ACM, 2023, pp. 3406-16, https://doi.org/10.1145/3543507.3583552.
+```
+"""
 import warnings
 from typing import Any, Mapping
 
@@ -17,14 +29,14 @@
 
 class VamanaIndex(index.Index):
     """
-    Open a Vamana index
+    Opens a `VamanaIndex`.
 
     Parameters
     ----------
     uri: str
-        URI of the index
+        URI of the index.
     config: Optional[Mapping[str, Any]]
-        config dictionary, defaults to None
+        TileDB config dictionary.
     """
 
     def __init__(
@@ -59,6 +71,9 @@ def __init__(
             self.size = self.base_size
 
     def get_dimensions(self):
+        """
+        Returns the dimension of the vectors in the index.
+        """
         return self.dimensions
 
     def query_internal(
@@ -69,16 +84,16 @@ def query_internal(
         **kwargs,
     ):
         """
-        Query an VAMANA index
+        Queries a `VamanaIndex`.
 
         Parameters
         ----------
-        queries: numpy.ndarray
-            ND Array of queries
+        queries: np.ndarray
+            2D array of query vectors. This can be used as a batch query interface by passing multiple queries in one call.
         k: int
-            Number of top results to return per query
+            Number of results to return per query vector.
         opt_l: int
-            How deep to search. Should be >= k. Defaults to 100.
+            How deep to search. Should be >= k, and if it's not, we will set it to k.
         """
         warnings.warn("The Vamana index is not yet supported, please use with caution.")
         if self.size == 0:
@@ -111,6 +126,23 @@ def create(
     storage_version: str = STORAGE_VERSION,
     **kwargs,
 ) -> VamanaIndex:
+    """
+    Creates an empty VamanaIndex.
+    Parameters
+    ----------
+    uri: str
+        URI of the index.
+    dimensions: int
+        Number of dimensions for the vectors to be stored in the index.
+    vector_type: np.dtype
+        Datatype of vectors.
+        Supported values (uint8, int8, float32).
+    config: Optional[Mapping[str, Any]]
+        TileDB config dictionary.
+    storage_version: str
+        The TileDB vector search storage version to use.
+        If not provided, use the latest stable storage version.
+    """
     warnings.warn("The Vamana index is not yet supported, please use with caution.")
     validate_storage_version(storage_version)
     ctx = vspy.Ctx(config)

documentation/Building.md

@@ -71,6 +71,20 @@ Credentials:
 - Some tests run on TileDB Cloud using your current environment variable `TILEDB_REST_TOKEN` - you will need a valid API token for the tests to pass. See [Create API Tokens](https://docs.tiledb.com/cloud/how-to/account/create-api-tokens) for for instructions on getting one.
 - For continuous integration, the token is configured for the `unittest` user and all tests should pass.
 
+## Quarto
+
+First install quarto with [their instructions](https://quarto.org/docs/get-started) or [with Homebrew](https://formulae.brew.sh/cask/quarto).
+
+Then run:
+
+```bash
+pip install quartodoc
+quartodoc build
+quarto render --fail-if-warnings
+```
+
+You can them open up `docs/documentation/index.html` in a web browser to preview the results.
+
 # Dependencies
 
 ## Linux