fix(notify): pass kwargs through notify_handler

README.md

@@ -1,5 +1,5 @@
 <!-- ---
-!-- Timestamp: 2026-02-16 10:13:53
+!-- Timestamp: 2026-03-16 17:14:33
 !-- Author: ywatanabe
 !-- File: /home/ywatanabe/proj/scitex-python/README.md
 !-- --- -->
@@ -43,7 +43,7 @@ SciTeX provides a **modular Python toolkit** that unifies the research workflow
 
 ## Demo
 
-**40 min, zero human intervention** — AI agent conducts full research pipeline:
+**40 min, minimal human intervention** — AI agent conducts full research pipeline:
 
 > Literature search → Data analysis → Statistics → Figures → 21-page manuscript → Peer review simulation
 
@@ -304,8 +304,20 @@ The SciTeX system follows the Four Freedoms for Research below, inspired by [the
 
 ---
 
+## Star History
+
+<a href="https://star-history.com/#ywatanabe1989/scitex-python&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ywatanabe1989/scitex-python&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ywatanabe1989/scitex-python&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ywatanabe1989/scitex-python&type=Date" />
+ </picture>
+</a>
+
+---
+
 <p align="center">
   <a href="https://scitex.ai" target="_blank"><img src="docs/assets/images/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a>
 </p>
 
-<!-- EOF -->
+<!-- EOF -->

docs/sphinx/generate_api_docs.py

@@ -1,69 +1,243 @@
 #!/usr/bin/env python3
-"""Generate API documentation files for SciTeX modules."""
+# noqa: STX-S001 — build utility, not a research script
+"""Generate API documentation stubs for all SciTeX public modules.
 
+Discovers modules automatically from the package directory.
+Generates both modules/*.rst stubs and updates modules/index.rst toctree.
+
+Usage:
+    python generate_api_docs.py           # Generate missing stubs only
+    python generate_api_docs.py --force   # Regenerate all stubs
+"""
+
+import sys
 from pathlib import Path
 
-# API documentation template
-API_TEMPLATE = """{module_name} API Reference
+# Template for module RST stub (minimal — Sphinx autodoc fills in the rest)
+MODULE_TEMPLATE = """{title}
 {underline}
 
-.. automodule:: {module_path}
+.. automodule:: scitex.{module_name}
    :members:
    :undoc-members:
    :show-inheritance:
-   :inherited-members:
+"""
 
-Submodules
-----------
+# Modules to skip (internal, private, or aliases)
+SKIP_MODULES = {
+    "_dev",
+    "_docs",
+    "_mcp_resources",
+    "_mcp_tools",
+    "__pycache__",
+    ".claude",
+    "fig",  # alias for plt
+    "ml",  # alias for ai
+    "dt",  # alias for datetime
+    "reproduce",  # alias for repro
+    "verify",  # alias for clew
+    "fts",  # internal bundle schemas
+    "errors",  # deprecated, use logging
+    "units",  # internal
+}
+
+# Module categories for the index (ordered)
+MODULE_CATEGORIES = {
+    "Core": [
+        "session",
+        "io",
+        "config",
+        "logging",
+        "repro",
+        "clew",
+    ],
+    "Science & Analysis": [
+        "stats",
+        "plt",
+        "dsp",
+        "diagram",
+        "canvas",
+    ],
+    "Literature & Writing": [
+        "scholar",
+        "writer",
+        "linter",
+        "notebook",
+    ],
+    "Machine Learning": [
+        "ai",
+        "nn",
+        "torch",
+        "cv",
+        "benchmark",
+    ],
+    "Data & I/O": [
+        "pd",
+        "db",
+        "dataset",
+        "schema",
+    ],
+    "Infrastructure": [
+        "app",
+        "cloud",
+        "container",
+        "tunnel",
+        "cli",
+        "browser",
+        "capture",
+        "audio",
+        "notify",
+        "social",
+    ],
+    "Utilities": [
+        "gen",
+        "template",
+        "decorators",
+        "introspect",
+        "str",
+        "dict",
+        "path",
+        "os",
+        "sh",
+        "git",
+        "parallel",
+        "linalg",
+        "datetime",
+        "types",
+        "rng",
+        "context",
+        "resource",
+        "utils",
+        "etc",
+        "web",
+        "msword",
+        "tex",
+        "bridge",
+        "compat",
+        "module",
+        "gists",
+        "media",
+        "security",
+        "ui",
+        "usage",
+        "dev",
+        "audit",
+    ],
+}
+
+
+def discover_modules(src_dir: Path) -> list[str]:
+    """Discover all public submodule directories."""
+    modules = []
+    for child in sorted(src_dir.iterdir()):
+        if not child.is_dir():
+            continue
+        name = child.name
+        if name.startswith("_") or name in SKIP_MODULES:
+            continue
+        if (child / "__init__.py").exists():
+            modules.append(name)
+    return modules
+
+
+def generate_stub(module_name: str, output_path: Path, force: bool = False):
+    """Generate a single RST stub file."""
+    if output_path.exists() and not force:
+        return False
+
+    title = f"{module_name} Module (``stx.{module_name}``)"
+    underline = "=" * len(title)
+
+    content = MODULE_TEMPLATE.format(
+        title=title,
+        underline=underline,
+        module_name=module_name,
+    )
 
-.. autosummary::
-   :toctree: generated
-   :recursive:
+    output_path.write_text(content)
+    return True
 
-   {module_path}
-"""
 
+def generate_index(modules_dir: Path, all_modules: list[str]):
+    """Generate modules/index.rst with all modules in categorized toctrees."""
+    # Collect categorized and uncategorized modules
+    categorized = set()
+    for mods in MODULE_CATEGORIES.values():
+        categorized.update(mods)
 
-def create_api_doc(module_name, module_path, output_file):
-    """Create an API documentation file for a module."""
-    title = f"scitex.{module_name}"
-    underline = "=" * len(title + " API Reference")
+    uncategorized = [m for m in all_modules if m not in categorized]
 
-    content = API_TEMPLATE.format(
-        module_name=title, module_path=module_path, underline=underline
-    )
+    # Build index content
+    lines = [
+        "Module Overview",
+        "===============",
+        "",
+        "SciTeX is organized into focused modules.",
+        "All modules are accessible via ``import scitex as stx`` followed by ``stx.<module>``.",
+        "",
+    ]
 
-    with open(output_file, "w") as f:
-        f.write(content)
-    print(f"Created: {output_file}")
+    for category, mods in MODULE_CATEGORIES.items():
+        # Only include modules that actually exist
+        existing = [m for m in mods if m in all_modules]
+        if not existing:
+            continue
 
+        lines.append(f".. toctree::")
+        lines.append(f"   :maxdepth: 2")
+        lines.append(f"   :caption: {category}")
+        lines.append(f"")
+        for m in existing:
+            lines.append(f"   {m}")
+        lines.append("")
 
-def main():
-    # Create API directory
-    api_dir = Path(__file__).parent / "api"
-    api_dir.mkdir(exist_ok=True)
-
-    # Define modules
-    modules = [
-        ("gen", "scitex.gen"),
-        ("io", "scitex.io"),
-        ("plt", "scitex.plt"),
-        ("dsp", "scitex.dsp"),
-        ("stats", "scitex.stats"),
-        ("pd", "scitex.pd"),
-        ("ai", "scitex.ai"),
-        ("nn", "scitex.nn"),
-        ("db", "scitex.db"),
-        ("decorators", "scitex.decorators"),
-        ("path", "scitex.path"),
-        ("str", "scitex.str"),
-        ("dict", "scitex.dict"),
-    ]
+    if uncategorized:
+        lines.append(".. toctree::")
+        lines.append("   :maxdepth: 2")
+        lines.append("   :caption: Other")
+        lines.append("")
+        for m in sorted(uncategorized):
+            lines.append(f"   {m}")
+        lines.append("")
 
-    # Create API documentation files
-    for module_name, module_path in modules:
-        output_file = api_dir / f"scitex.{module_name}.rst"
-        create_api_doc(module_name, module_path, output_file)
+    (modules_dir / "index.rst").write_text("\n".join(lines))
+
+
+def main():
+    force = "--force" in sys.argv
+
+    # Paths
+    script_dir = Path(__file__).parent
+    src_dir = script_dir.parent.parent / "src" / "scitex"
+    # Output to source/api/ (where Sphinx actually reads from)
+    modules_dir = script_dir / "source" / "api"
+    modules_dir.mkdir(parents=True, exist_ok=True)
+
+    if not src_dir.exists():
+        print(f"Error: Source directory not found: {src_dir}")
+        sys.exit(1)
+
+    # Discover all public modules
+    all_modules = discover_modules(src_dir)
+    print(f"Discovered {len(all_modules)} public modules")
+
+    # Generate stubs
+    created = 0
+    skipped = 0
+    for module_name in all_modules:
+        output_path = modules_dir / f"{module_name}.rst"
+        if generate_stub(module_name, output_path, force=force):
+            created += 1
+            print(f"  Created: {module_name}.rst")
+        else:
+            skipped += 1
+
+    # Generate index
+    generate_index(modules_dir, all_modules)
+    print(f"  Updated: index.rst")
+
+    print(f"\nDone: {created} created, {skipped} existing (skipped)")
+    print(f"Total modules documented: {len(all_modules)}")
 
 
 if __name__ == "__main__":

docs/sphinx/modules/app.rst

@@ -0,0 +1,7 @@
+app Module (``stx.app``)
+========================
+
+.. automodule:: scitex.app
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/sphinx/modules/audio.rst

@@ -0,0 +1,7 @@
+audio Module (``stx.audio``)
+============================
+
+.. automodule:: scitex.audio
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/sphinx/modules/audit.rst

@@ -0,0 +1,7 @@
+audit Module (``stx.audit``)
+============================
+
+.. automodule:: scitex.audit
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/sphinx/modules/benchmark.rst

@@ -0,0 +1,7 @@
+benchmark Module (``stx.benchmark``)
+====================================
+
+.. automodule:: scitex.benchmark
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/sphinx/modules/bridge.rst

@@ -0,0 +1,7 @@
+bridge Module (``stx.bridge``)
+==============================
+
+.. automodule:: scitex.bridge
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/sphinx/modules/browser.rst

@@ -0,0 +1,7 @@
+browser Module (``stx.browser``)
+================================
+
+.. automodule:: scitex.browser
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/sphinx/modules/canvas.rst

@@ -0,0 +1,7 @@
+canvas Module (``stx.canvas``)
+==============================
+
+.. automodule:: scitex.canvas
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/sphinx/modules/capture.rst

@@ -0,0 +1,7 @@
+capture Module (``stx.capture``)
+================================
+
+.. automodule:: scitex.capture
+   :members:
+   :undoc-members:
+   :show-inheritance: