Merge pull request #25 from tlambert03/docs

add docs

Author: tlambert03

.github/workflows/docs.yaml

@@ -0,0 +1,29 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    name: Deploy Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+      - uses: astral-sh/setup-uv@v6
+      - name: Deploy documentation
+        run: uv run --group docs mkdocs gh-deploy --strict --force

.gitignore

@@ -11,6 +11,7 @@ build
 dist
 .vscode
 docs/_build/
+site
 
 # remove me to enforce synchrony across development environments
 uv.lock

docs/index.md

@@ -0,0 +1,91 @@
+# spatial-graph
+
+`spatial-graph` provides a data structure for directed and undirected graphs,
+where each node has an nD position (in time or space).
+
+It leverages well-in-time compiled C++ code for efficient graph operations,
+coupled with an rtree implementation for fast spatial queries.
+
+## Goals
+
+- Support for arbitrary number of dimensions
+- Typed node identifiers and attributes
+    - Any fixed-length type that is supported by `numpy`
+- Efficient node/edge queries by
+    - ROI
+    - kNN (by points / lines)
+- numpy-like interface for efficient:
+    - Graph population and manipulation
+    - Query results
+    - Attribute access
+- Minimal memory footprint
+- Minimal dependencies
+- PYX API for graph algorithms in C/C++
+
+## Basic Usage
+
+Graph creation:
+
+```python
+graph = sg.SpatialGraph(
+    ndims=3,
+    node_dtype="uint64",
+    node_attr_dtypes={"position": "double[3]"},
+    edge_attr_dtypes={"score": "float32"},
+    position_attr="position",
+    directed=False,
+)
+```
+
+Adding nodes/edges:
+
+```python
+graph.add_nodes(
+    np.array([1, 2, 3, 4, 5], dtype="uint64"),
+    position=np.array(
+        [
+            [0.1, 0.1, 0.1],
+            [0.2, 0.2, 0.2],
+            [0.3, 0.3, 0.3],
+            [0.4, 0.4, 0.4],
+            [0.5, 0.5, 0.5],
+        ],
+        dtype="double",
+    ),
+)
+
+graph.add_edges(
+    np.array([[1, 2], [3, 4], [5, 1]], dtype="uint64"),
+    score=np.array([0.2, 0.3, 0.4], dtype="float32"),
+)
+```
+
+Query nodes/edges in ROI:
+
+```python
+# nodes/edges will be numpy arrays of dtype uint64 and shape (n,)/(n, 2)
+nodes = graph.query_nodes_in_roi(np.array([[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]]))
+edges = graph.query_edges_in_roi(np.array([[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]]))
+```
+
+Query nodes/edges by position:
+
+```python
+nodes = graph.query_nearest_nodes(np.array([0.3, 0.3, 0.3]), k=3)
+edges = graph.query_nearest_edges(np.array([0.3, 0.3, 0.3]), k=3)
+```
+
+Access node/edge attributes:
+
+```python
+node_positions = graph.node_attrs[nodes].position
+edge_scores = graph.edge_attrs[edges].score
+```
+
+Delete nodes/edges:
+
+```python
+graph.remove_nodes(nodes[:1000])
+```
+
+See the [API documentation](./reference) for more details.

mkdocs.yml

@@ -0,0 +1,42 @@
+site_name: "spatial-graph"
+site_url: https://github.com/funkelab/spatial_graph
+site_description: >-
+  High performance spatial graph library for Python
+# Repository
+repo_name: funkelab/spatial_graph
+repo_url: https://github.com/funkelab/spatial_graph
+
+theme:
+
+  name: material
+  palette:
+    scheme: default
+    primary: pink
+  features:
+    - content.tabs.link
+    - content.code.copy
+    - content.code.annotate
+    - navigation.instant
+
+plugins:
+  - search
+  - api-autonav:
+      modules: ["src/spatial_graph"]
+  - mkdocstrings:
+      handlers:
+        python:
+          inventories:
+            - https://docs.python.org/3/objects.inv
+          options:
+            docstring_section_style: list # or "table"
+            docstring_style: "numpy"
+            filters: ["!^_"]
+            heading_level: 1
+            merge_init_into_class: true
+            parameter_headings: true
+            separate_signature: true
+            show_root_heading: true
+            show_signature_annotations: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            summary: true

pyproject.toml

@@ -31,14 +31,20 @@ classifiers = [
 dependencies = ["witty>=v0.2.1", "CT3>=3.3.3", "numpy", "setuptools>=75.8.0"]
 
 [dependency-groups]
+test = ["pytest>=8.3.5", "pytest-cov>=6.1.1"]
 dev = [
+  { include-group = "test" },
   "ipython>=8.18.1",
   "mypy>=1.15.0",
   "pre-commit>=4.2.0",
-  "pytest>=8.3.5",
-  "pytest-cov>=6.1.1",
   "ruff>=0.11.10",
 ]
+docs = [
+  "mkdocs>=1.6.1",
+  "mkdocs-api-autonav>=0.3.0",
+  "mkdocs-material>=9.6.15",
+  "mkdocstrings-python>=1.16.12",
+]
 
 
 [project.urls]