API reference refinements

Author: JohnGoertz-SB

.github/workflows/docs.yml

@@ -17,5 +17,5 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - run: pip install mkdocs mkdocs-marimo mkdocs-material mkdocstrings-python mkdocs-autoapi
+      - run: pip install mkdocs mkdocs-marimo mkdocs-material mkdocstrings-python
       - run: mkdocs gh-deploy --force

docs/api/quantization.md

@@ -0,0 +1,5 @@
+::: vsup.quantization
+  handler: python
+  options:
+    show_root_heading: false
+    show_source: false

docs/api/transforms.md

@@ -0,0 +1,5 @@
+::: vsup.transforms
+  handler: python
+  options:
+    show_root_heading: false
+    show_source: false

docs/api/vsup.md

@@ -0,0 +1,5 @@
+::: vsup.vsup
+  handler: python
+  options:
+    show_root_heading: true
+    show_source: false

mkdocs.yml

@@ -2,7 +2,8 @@ site_name: VSUP
 
 theme:
   name: "material"
-# theme: readthedocs
+  features:
+    - navigation.sections
 
 repo_name: VSUP
 repo_url: https://github.com/JohnGoertz/vsup
@@ -11,9 +12,11 @@ site_url: https://JohnGoertz.github.io/vsup
 plugins:
 - search
 - marimo
-- mkdocs-autoapi:
-    autoapi_dir: vsup
-- mkdocstrings
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          docstring_style: numpy
 
 markdown_extensions:
   - admonition
@@ -30,3 +33,7 @@ markdown_extensions:
 
 nav:
   - Overview: index.md
+  - API Reference:
+    - vsup: api/vsup.md
+    - quantization: api/quantization.md
+    - transforms: api/transforms.md

pyproject.toml

@@ -58,7 +58,6 @@ exclude_lines = [
 [dependency-groups]
 dev = [
     "mkdocs>=1.6.1",
-    "mkdocs-autoapi>=0.4.1",
     "mkdocs-marimo>=0.2.1",
     "mkdocs-material>=9.6.15",
     "mkdocstrings-python>=1.16.12",

uv.lock

@@ -1,18 +1,20 @@
 """
-Quantization functions for VSUP.
+## Quantization functions for VSUP.
 
 This module provides functions for quantizing value and uncertainty pairs
 into discrete levels for visualization. Quantization is an important step in
 VSUP that helps reduce the complexity of the visualization while maintaining
 the essential patterns in the data.
 
 The module provides two quantization strategies:
+
 1. Linear quantization: Independently bins values and uncertainties into
    equal-width intervals. This is simpler but may not capture the relationship
    between value and uncertainty.
 2. Tree quantization: Uses a hierarchical approach where the number of value
    bins depends on the uncertainty level. Higher uncertainty means fewer value
    bins, reflecting the reduced confidence in precise value distinctions.
+
 """
 
 import numpy as np

vsup/quantization.py

@@ -1,5 +1,5 @@
 """
-Color transformation functions for VSUP.
+## Color transformation functions for VSUP.
 
 This module provides functions for converting between different color spaces
 and applying uncertainty-based transformations to colors using CIELAB color space.
@@ -8,9 +8,11 @@
 of the data while maintaining the ability to distinguish values.
 
 The module provides three transformation modes:
+
 1. USL: Uncertainty affects both saturation and lightness
 2. US: Uncertainty affects saturation only
 3. UL: Uncertainty affects lightness only
+
 """
 
 import numpy as np
@@ -40,7 +42,7 @@ def usl_transform(
         Minimum saturation/chroma (0 to 1). Higher values ensure colors
         remain visible even at high uncertainty. Default is 0.0.
     lmax : float, optional
-        Maximum lightness (0 to 1). The maximum lightness will be 100 * lmax.
+        Maximum lightness (0 to 1). The maximum lightness will be 100 \* lmax.
         Controls how white the colors become at high uncertainty.
         Default is 1.0.
 

vsup/transforms.py

@@ -1,20 +1,22 @@
 """
-Value-Suppressing Uncertainty Palettes (VSUP) for visualizing data with uncertainty.
+## Value-Suppressing Uncertainty Palettes (VSUP) for visualizing data with uncertainty.
 
 This module provides a class for creating and using VSUPs to visualize data with uncertainty
 by mapping both value and uncertainty to color properties. VSUPs are a visualization technique
 that encodes both the value and its uncertainty in a single color, making it easier to
 understand the reliability of the data while maintaining the ability to distinguish values.
 
 The module supports three visualization modes:
+
 - USL: Uncertainty mapped to both Saturation and Lightness
 - US: Uncertainty mapped to Saturation only
 - UL: Uncertainty mapped to Lightness only
 
-Note that transformations take place in the CIELAB color space: L-modes increase L* (lightness),
-while S-modes decrease "chroma": a* (green-red) and b* (blue-yellow), equally.
+Note that transformations take place in the CIELAB color space: L-modes increase L\* (lightness),
+while S-modes decrease "chroma": a\* (green-red) and b\* (blue-yellow), equally.
 
 It also provides two quantization methods:
+
 - Linear: Independent binning of values and uncertainties
 - Tree: Value bins depend on uncertainty level (higher uncertainty = fewer value bins)
 """
@@ -77,7 +79,7 @@ class VSUP:
         Minimum saturation/chroma (0 to 1). Default is 0.2. Higher values ensure
         colors remain visible even at high uncertainty.
     lmax : float, optional
-        Maximum lightness (0 to 1). The maximum lightness will be 100 * lmax.
+        Maximum lightness (0 to 1). The maximum lightness will be 100 \* lmax.
         Default is 0.9. Controls how white the colors become at high uncertainty.
     """