more reference-docs updates

datastax · Feb 4, 2025 · 4d85b05 · 4d85b05
1 parent cb28919
commit 4d85b05
Show file tree

Hide file tree

Showing 30 changed files with 331 additions and 291 deletions.
diff --git a/docs/_quartodoc.yml b/docs/_quartodoc.yml
@@ -1,13 +1,14 @@
 quartodoc:
   package: null
+  parser: numpy
   style: pkgdown
   render_interlinks: true
   renderer:
     style: markdown
     table_style: description-list
-  rewrite_all_pages: true
   options:
     include_attributes: true
+    signature_name: full
   title: 'API Reference'
   sidebar:
     file: "reference/_sidebar.yml"
@@ -18,41 +19,73 @@ quartodoc:
     contents:
       - "{{ contents }}"
   sections:
+
   - title: graph_retriever
     desc: |
       Base package providing traversal functionality.
     package: graph_retriever
     contents:
-    - name: traverse
-    - name: atraverse
+    - kind: page
+      path: traversal
+      summary:
+        name: Traversal
+        desc: "Methods to perform Graph Traversal"
+      flatten: true
+      contents:
+      - atraverse
+      - traverse
     - name: Adapter
+      package: graph_retriever.adapters
     - name: Content
-    - name: Edge
-    - name: Edges
-    - name: EdgeSpec
-    - name: EdgeFunction
-    - name: Id
-    - name: IdEdge
-    - name: MetadataEdge
-    - name: Node
-  - subtitle: 'edges'
-    contents:
-    - name: MetadataEdgeFunction
-      package: 'graph_retriever.edges:metadata'
+    - kind: page
+      path: node_types
+      summary:
+        name: Node types
+        desc: "Types related to working with Nodes"
+      flatten: true
+      contents:
+      - Node
+      - Edge
+      - MetadataEdge
+      - IdEdge
+      - Edges
+      - EdgeFunction
+    - kind: page
+      path: edge_types
+      summary:
+        name: Edge types
+        desc: "Types related to defining Edges"
+      flatten: true
+      contents:
+      - EdgeSpec
+      - Id
+      - name: MetadataEdgeFunction
+        package: 'graph_retriever.edges:metadata'
   - subtitle: 'strategies'
+    package: 'graph_retriever.strategies'
     contents:
     - name: Eager
-      package: 'graph_retriever.strategies:eager'
     - name: Mmr
-      package: 'graph_retriever.strategies:mmr'
+    - name: Scored
     - name: Strategy
-      package: 'graph_retriever.strategies'
+
   - title: langchain_graph_retriever
     desc: |
-      Traversal functionality integrated as a LangChain retriever supporting a variety of LangChain `VectorStore`s.
+      Traversal integrated as a LangChain Retriever supporting various VectorStores.
     package: langchain_graph_retriever
     contents:
-    - name: GraphRetriever
+    - kind: page
+      path: GraphRetriever
+      summary:
+        name: GraphRetriever
+        desc: "Provides a graph-based retriever combining vector search and graph traversal"
+      flatten: true
+      contents:
+      - name: GraphRetriever
+        exclude:
+        - apply_extra
+      - GraphRetriever._aget_relevant_documents
+      - GraphRetriever._get_relevant_documents
     - name: document_graph
   - subtitle: 'document_transformers'
     contents:
@@ -70,10 +103,6 @@ quartodoc:
       package: 'langchain_graph_retriever.document_transformers:spacy'
   - subtitle: 'adapters'
     contents:
-    - name: LangchainAdapter
-      package: 'langchain_graph_retriever.adapters:langchain'
-    - name: DenormalizedAdapter
-      package: 'langchain_graph_retriever.adapters:langchain'
     - name: AstraAdapter
       package: 'langchain_graph_retriever.adapters:astra'
     - name: CassandraAdapter
@@ -84,21 +113,36 @@ quartodoc:
       package: 'langchain_graph_retriever.adapters:in_memory'
     - name: OpenSearchAdapter
       package: 'langchain_graph_retriever.adapters:open_search'
+    - name: LangchainAdapter
+      package: 'langchain_graph_retriever.adapters:langchain'
+    - name: DenormalizedAdapter
+      package: 'langchain_graph_retriever.adapters:langchain'
     - name: 'inference'
       package: 'langchain_graph_retriever.adapters'
       members:
         - infer_adapter
+
   - title: graph_rag_example_helpers
     desc: |
       Helpers used in various examples and notebooks.
     package: graph_rag_example_helpers
     contents:
-    - name: initialize_environment
-    - name: Environment
+    - kind: page
+      path: environment
+      summary:
+        name: Environment
+        desc: "Helpers to setup the environment"
+      flatten: true
+      contents:
+      - initialize_environment
+      - Environment
   - subtitle: datasets
+    package: 'graph_rag_example_helpers.datasets'
     contents:
-    - name: aload_2wikimultihop
-      package: 'graph_rag_example_helpers.datasets.wikimultihop:load'
-
-
-
+    - name: animals
+      members:
+        - fetch_documents
+    - name: wikimultihop
+      members:
+        - aload_2wikimultihop
+        - BatchPreparer
diff --git a/docs/reference/_metadata.yml b/docs/reference/_metadata.yml
diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/__init__.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/__init__.py
@@ -1,5 +0,0 @@
-from .animals import fetch_animal_documents
-
-__all__ = [
-    "fetch_animal_documents",
-]

diff --git a/...ages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/animals/__init__.py b/...ages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/animals/__init__.py
@@ -0,0 +1,5 @@
+from .fetch import fetch_documents
+
+__all__ = [
+    "fetch_documents",
+]
diff --git a/...h_rag_example_helpers/datasets/animals.py → ...example_helpers/datasets/animals/fetch.py b/...h_rag_example_helpers/datasets/animals.py → ...example_helpers/datasets/animals/fetch.py
@@ -6,7 +6,7 @@
 ANIMALS_JSONL_URL = "https://raw.githubusercontent.com/datastax/graph-rag/refs/heads/main/data/animals.jsonl"
 
 
-def fetch_animal_documents() -> list[Document]:
+def fetch_documents() -> list[Document]:
     """
     Download and parse a list of Documents for use with Graph Retriever.
 
@@ -18,8 +18,8 @@ def fetch_animal_documents() -> list[Document]:
 
     Returns
     -------
-    list[Document]
-        The fetched animal documetns.
+    :
+        The fetched animal documents.
     """
     response = requests.get(ANIMALS_JSONL_URL)
     response.raise_for_status()  # Ensure we got a valid response

diff --git a/...graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/wikimultihop/__init__.py b/...graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/wikimultihop/__init__.py
@@ -1,5 +1,6 @@
-from .load import aload_2wikimultihop
+from .load import BatchPreparer, aload_2wikimultihop
 
 __all__ = [
     "aload_2wikimultihop",
+    "BatchPreparer",
 ]
diff --git a/...ges/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/wikimultihop/load.py b/...ges/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/wikimultihop/load.py
@@ -50,6 +50,7 @@ def wikipedia_lines(para_with_hyperlink_zip_path: str) -> Iterable[bytes]:
 MAX_RETRIES = 8
 
 BatchPreparer = Callable[[Iterator[bytes]], Iterator[Document]]
+"""Function to apply to batches of lines to produce the document."""
 
 
 async def aload_2wikimultihop(

diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/env.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/env.py
@@ -8,15 +8,18 @@ class Environment(Enum):
     """Enumeration of supported environments for examples."""
 
     CASSIO = auto()
+    """Environment variables for connecting to AstraDB via CassIO"""
+
     ASTRAPY = auto()
+    """Environment variables for connecting to AstraDB via AstraPy"""
 
     def required_envvars(self) -> list[str]:
         """
         Return the required environment variables for this environment.
 
         Returns
         -------
-        list[str]
+        :
             The environment variables required in this environment.
 
         Raises
@@ -95,10 +98,19 @@ def initialize_environment(env: Environment = Environment.CASSIO):
     """
     Initialize the environment variables.
 
-    This uses the following:
-    1. If a `.env` file is found, load environment variables from that.
-    2. If not, and running in colab, set necessary environment variables from secrets.
-    3. If necessary variables aren't set by the above, then prompts the user.
+    Parameters
+    ----------
+    env : Environment, default Environment.CASSIO
+        The environment to initialize
+
+    Notes
+    -----
+        This uses the following:
+
+        1. If a `.env` file is found, load environment variables from that.
+        2. If not, and running in colab, set necessary environment variables from
+            secrets.
+        3. If necessary variables aren't set by the above, then prompts the user.
     """
     # 1. If a `.env` file is found, load environment variables from that.
     if (dotenv_path := find_dotenv()) is not None:

diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/persistent_iteration.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/persistent_iteration.py
@@ -73,7 +73,7 @@ def __iter__(self) -> Iterator[tuple[Offset, T]]:
 
         Returns
         -------
-        Iterator[T]
+        :
         """
         return self
 
@@ -91,7 +91,7 @@ def ack(self, offset: Offset) -> int:
 
         Returns
         -------
-        int
+        :
             The numebr of pending elements.
         """
         self._write_journal.write(f"{offset.index}\n")
@@ -107,7 +107,7 @@ def pending_count(self) -> int:
 
         Returns
         -------
-        int
+        :
             The number of pending elements.
         """
         return len(self.pending)
@@ -118,7 +118,7 @@ def completed_count(self) -> int:
 
         Returns
         -------
-        int
+        :
             The number of completed elements.
         """
         return len(self._completed)