Thoth

SKILL.md

---
name: thoth
description: "Thoth Standard -- Auto-Documentation Engine. Reads your entire project and generates README, API reference, and usage guide. Saved to .md files."
version: "1.0.0"
metadata:
  openclaw:
    requires:
      env: [PROJECT_PATH, LICENSE_KEY]
      bins: [python3, pip3]
    primaryEnv: PROJECT_PATH
    emoji: "📜📖"
    homepage: https://clawhub.ai/occupythemilkyway/thoth
    tags: [documentation, readme, api-reference, code, autodoc, developer, standard, thoth]
    envVars:
      - name: LICENSE_KEY
        required: true
        description: "Your Thoth Standard license key. Get one at: ko-fi.com/occupythemilkyway"
      - name: PROJECT_PATH
        required: true
        description: "Path to the project folder to document"
      - name: PROJECT_NAME
        required: false
        description: "Project name override (default: folder name)"
        default: ""
      - name: OUTPUT_DIR
        required: false
        description: "Directory to save docs (default: ./docs)"
        default: "./docs"
---

# Thoth Standard -- Auto-Documentation Engine

Full project documentation in minutes. README, API reference, usage guide -- all saved to files.

---

## Step 1 -- Install

```bash
pip3 install rich --break-system-packages --quiet
```

---

## Step 2 -- Validate and scan

```python
import os, sys, ast
from datetime import datetime
from rich.console import Console
from rich.panel import Panel
from rich.tree import Tree
from rich.table import Table
from rich import box

console = Console()

LICENSE_KEY = os.environ.get("LICENSE_KEY", "").strip()
if not LICENSE_KEY or not LICENSE_KEY.startswith("THOTH-STD-"):
    console.print(Panel(
        "[red bold]Thoth Standard requires a license key.[/red bold]\n\n"
        "Get your key at: [bold cyan]ko-fi.com/occupythemilkyway[/bold cyan]\n\n"
        "Or use the free version: [dim]openclaw skills install thoth-lite[/dim]",
        title="License Required",
        border_style="red"
    ))
    sys.exit(1)

PROJECT_PATH = os.environ.get("PROJECT_PATH", "").strip()
PROJECT_NAME = os.environ.get("PROJECT_NAME", "").strip()
OUTPUT_DIR   = os.environ.get("OUTPUT_DIR", "./docs").strip()

if not PROJECT_PATH or not os.path.exists(PROJECT_PATH):
    console.print(Panel(f"[red]PROJECT_PATH not found: {PROJECT_PATH}[/red]", title="Error", border_style="red"))
    sys.exit(1)

if not PROJECT_NAME:
    PROJECT_NAME = os.path.basename(os.path.abspath(PROJECT_PATH))

os.makedirs(OUTPUT_DIR, exist_ok=True)

console.print()
console.print(Panel.fit(
    f"[bold cyan]📜 Thoth Standard -- Auto-Documentation[/bold cyan]\n"
    f"Project: [yellow]{PROJECT_NAME}[/yellow]\n"
    f"Path:    [dim]{PROJECT_PATH}[/dim]\n"
    f"Output:  [green]{OUTPUT_DIR}/[/green]",
    border_style="cyan"
))

SKIP_DIRS = {".git", "__pycache__", "node_modules", ".venv", "venv", "dist", "build", ".next", ".pytest_cache"}
CODE_EXTS  = {".py", ".js", ".ts", ".jsx", ".tsx", ".go", ".rs", ".java", ".rb", ".cs", ".cpp", ".c", ".sh"}
META_FILES = {"requirements.txt", "package.json", "pyproject.toml", "go.mod", "Cargo.toml", "setup.py", "setup.cfg"}

all_files, meta_files, functions = [], {}, []

for root, dirs, fnames in os.walk(PROJECT_PATH):
    dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
    for fname in fnames:
        full = os.path.join(root, fname)
        rel  = os.path.relpath(full, PROJECT_PATH)
        ext  = os.path.splitext(fname)[1].lower()
        if fname in META_FILES:
            try:
                with open(full, encoding="utf-8", errors="replace") as fh:
                    meta_files[fname] = fh.read(2000)
            except Exception:
                pass
        if ext in CODE_EXTS:
            all_files.append((rel, full, ext))

# Extract Python functions/classes for API reference
for rel, full, ext in all_files:
    if ext == ".py":
        try:
            with open(full, encoding="utf-8", errors="replace") as fh:
                source = fh.read()
            tree = ast.parse(source)
            for node in ast.walk(tree):
                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
                    doc = ast.get_docstring(node) or ""
                    args = []
                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                        args = [a.arg for a in node.args.args]
                    functions.append({
                        "file": rel, "name": node.name,
                        "type": "class" if isinstance(node, ast.ClassDef) else "function",
                        "args": args, "doc": doc[:200]
                    })
        except Exception:
            pass

tbl = Table(title=f"Project Scan: {PROJECT_NAME}", box=box.ROUNDED, border_style="cyan")
tbl.add_column("Metric", style="dim")
tbl.add_column("Value", style="yellow")
tbl.add_row("Code files", str(len(all_files)))
tbl.add_row("Python symbols", str(len(functions)))
tbl.add_row("Meta files", ", ".join(meta_files.keys()) or "none")
tbl.add_row("Output dir", OUTPUT_DIR)
console.print(tbl)

# Print file tree and contents for Claude
console.print("\n[bold]Project structure:[/bold]")
for rel, full, ext in sorted(all_files)[:30]:
    print(f"  {rel}")

console.print("\n[bold]File contents (for documentation):[/bold]")
for rel, full, ext in sorted(all_files)[:25]:
    try:
        with open(full, encoding="utf-8", errors="replace") as fh:
            content = fh.read(4000)
        print(f"\n=== {rel} ===\n{content}\n=== END {rel} ===")
    except Exception:
        pass

if functions:
    console.print("\n[bold]Extracted symbols:[/bold]")
    for fn in functions[:50]:
        args_str = ", ".join(fn["args"]) if fn["type"] == "function" else ""
        print(f"  [{fn['type']}] {fn['file']}::{fn['name']}({args_str}) -- {fn['doc'][:80]}")

for name, content in meta_files.items():
    print(f"\n=== META: {name} ===\n{content}\n=== END META ===")
```

---

## Step 3 -- Generate documentation

Based on the project scan above, generate three complete documents:

### Document 1: README.md
```
# [PROJECT_NAME]
> Tagline

## Overview
What it does, why it exists, who it's for. (3-4 paragraphs, thorough)

## Features
Bullet list of all features found in the code.

## Installation
Exact install steps based on the actual meta files found.

## Quick Start
Working code example.

## Usage
Detailed usage with multiple examples.

## Configuration
All config options, env vars, or settings found.

## Project Structure
File/folder explanations.

## License
```

### Document 2: API_REFERENCE.md
For every function, class, and method found in the scan:
```
# API Reference: [PROJECT_NAME]

## [module_name]

### `function_name(args)`
Description of what it does, parameters, return value, example.
```

### Document 3: USAGE_GUIDE.md
Practical, real-world usage guide with worked examples from the actual code.

---

## Step 4 -- Save and confirm

```python
import os
from rich.console import Console
from rich.panel import Panel
from rich.table import Table
from rich import box
console = Console()

# (Claude saves the 3 files above to OUTPUT_DIR using its file tool)
readme_path  = os.path.join(OUTPUT_DIR, "README.md")
api_path     = os.path.join(OUTPUT_DIR, "API_REFERENCE.md")
usage_path   = os.path.join(OUTPUT_DIR, "USAGE_GUIDE.md")

tbl = Table(title="Documentation Generated", box=box.SIMPLE, border_style="green")
tbl.add_column("File", style="cyan")
tbl.add_column("Description", style="dim")
tbl.add_row(readme_path,  "Project overview and install")
tbl.add_row(api_path,     "Full API reference")
tbl.add_row(usage_path,   "Practical usage guide")
console.print()
console.print(tbl)
console.print(Panel(
    "[bold green]Documentation complete![/bold green]\n\n"
    "Upgrade to [magenta]Thoth Pro ($9)[/magenta] for auto-injected docstrings, git CHANGELOG, and architecture docs.\n"
    "-> [cyan]ko-fi.com/occupythemilkyway[/cyan]",
    border_style="green"
))
```

Save all three documents to OUTPUT_DIR using your file writing tool, then display the confirmation panel.