generate_docs.py

#!/usr/bin/env python3
"""
Generate Markdown documentation from Nix options JSON.
This script processes the options.json file generated by options-document.nix
and creates organized Markdown files in the docs directory for VitePress.
"""

import json
import os
import re
from collections import defaultdict
from pathlib import Path
from typing import Dict, List, Any

# Configuration
OPTIONS_JSON_PATH = "result/options.json/share/doc/nixos/options.json"
DOCS_OUTPUT_DIR = "docs"

def load_options() -> Dict[str, Any]:
    """Load the options from the JSON file."""
    with open(OPTIONS_JSON_PATH, 'r') as f:
        return json.load(f)

def categorize_options(options: Dict[str, Any]) -> Dict[str, Dict[str, List[Dict[str, Any]]]]:
    """
    Categorize options by their group and subgroup.
    For example, 'perSystem.snow-blower.integrations.agenix.package' would be
    categorized under {'integrations': {'agenix': [option_data]}}

    Special cases:
    - dotenv, just.package, process-compose.package, shell, etc. are handled as one level deep
    """
    categorized = defaultdict(lambda: defaultdict(list))

    # Define special cases that should only go one level deep
    one_level_deep = [
        "dotenv",
        "just",
        "process-compose",
        "processes",
        "scripts",
        "shell"
    ]

    for option_key, option_data in options.items():
        # Skip options that don't match our expected pattern
        if not option_key.startswith("perSystem.snow-blower."):
            continue

        # Extract the parts after 'perSystem.snow-blower.'
        parts = option_key.split("perSystem.snow-blower.")[1].split(".")

        # Add the full option key to the data for reference
        option_data["_key"] = option_key

        # Check if this is a special case that should only go one level deep
        is_special_case = False
        for special_case in one_level_deep:
            special_parts = special_case.split(".")
            if len(parts) >= len(special_parts) and ".".join(parts[:len(special_parts)]) == special_case:
                group = parts[0]  # e.g., 'dotenv', 'shell', etc.
                categorized[group]["_all"].append(option_data)
                is_special_case = True
                break

        # If not a special case and has at least 2 parts, use the standard categorization
        if not is_special_case and len(parts) >= 2:
            group = parts[0]  # e.g., 'integrations'
            subgroup = parts[1]  # e.g., 'agenix'
            categorized[group][subgroup].append(option_data)

    return categorized

def format_type(type_str: str) -> str:
    """Format the type string for better readability in Markdown."""
    # Clean up common type patterns
    type_str = re.sub(r'<(?:function|lambda).*?>', '`function`', type_str)
    type_str = re.sub(r'<.*?>', '', type_str)

    # Wrap in code blocks
    if not type_str.startswith('`'):
        type_str = f'`{type_str}`'

    return type_str

def format_default(default_value: Any) -> str:
    """Format the default value for Markdown."""
    if default_value is None:
        return "_No default_"

    # Handle dictionary format with _type and text fields
    if isinstance(default_value, dict) and "_type" in default_value and "text" in default_value:
        text = default_value["text"]
        if text.strip() == "":
            return "_Empty string_"
        return f'```nix\n{text}\n```'

    # Handle string values
    if isinstance(default_value, str):
        if default_value.strip() == "":
            return "_Empty string_"
        return f'```nix\n{default_value}\n```'

    # Handle other types
    return f'```nix\n{default_value}\n```'

def format_example(example: Any) -> str:
    """Format an example value for Markdown."""
    if example is None:
        return ""

    # Handle dictionary format with _type and text fields
    if isinstance(example, dict) and "_type" in example and "text" in example:
        text = example["text"]
        if text.strip() == "":
            return "_Empty string_"
        return f'```nix\n{text}\n```'

    # Handle string values
    if isinstance(example, str):
        if example.strip() == "":
            return "_Empty string_"
        return f'```nix\n{example}\n```'

    # Handle other types
    return f'```nix\n{example}\n```'

def generate_markdown(group: str, subgroup: str, options: List[Dict[str, Any]]) -> str:
    """Generate a Markdown document for a specific group and subgroup."""
    if subgroup == "_all":
        title = f"{group.capitalize()}"
        description = f"Options for configuring {group}."
    else:
        title = f"{subgroup.capitalize()} ({group})"
        description = f"Options for configuring {subgroup} in the {group} category."

    md = [
        f"## Options",
        "",
    ]

    # Sort options by name for consistent output
    options.sort(key=lambda x: x.get("_key", ""))

    for option in options:
        option_key = option.get("_key", "")

        # Extract the short key with context
        parts = option_key.split(".")
        if len(parts) > 3 and parts[0] == "perSystem" and parts[1] == "snow-blower":
            # For options like perSystem.snow-blower.languages.javascript.bun.enable
            # We want to show: bun.enable
            if subgroup != "_all":
                # Find the subgroup in the parts and get everything after it
                try:
                    subgroup_index = parts.index(subgroup)
                    short_key = ".".join(parts[subgroup_index+1:])
                except ValueError:
                    short_key = parts[-1]
            else:
                # For _all category, just use the last part
                short_key = parts[-1]
        else:
            # Fallback to just the last part
            short_key = parts[-1] if parts else ""

        # Escape angle brackets for VitePress rendering
        display_short_key = short_key.replace("<", "\\<").replace(">", "\\>")
        display_option_key = option_key.replace("<", "\\<").replace(">", "\\>")

        md.append(f"### {display_short_key}")
        md.append(f"**Location:** *{display_option_key}*")
        md.append("")

        # Description
        if "description" in option and option["description"]:
            md.append(option["description"])
            md.append("")

        # Type
        if "type" in option:
            md.append(f"**Type:**\n")
            md.append(f"{format_type(option['type'])}")
            md.append("")

        # Default value
        if "default" in option:
            md.append(f"**Default:**\n{format_default(option['default'])}")
            md.append("")

        # Example
        if "example" in option and option["example"]:
            md.append("**Example:**")
            md.append("")
            md.append(format_example(option["example"]))
            md.append("")

        # Declarations (source files)
        if "declarations" in option and option["declarations"]:
            md.append("**Declared by:**")
            md.append("")
            for decl in option["declarations"]:
                if isinstance(decl, dict) and "url" in decl and "name" in decl:
                    url = decl['url']
                    if not url.endswith('.nix'):
                        url = f"{url}/default.nix"
                    md.append(f"- [{decl['name']}](https://github.com/use-the-fork/snow-blower/tree/main/{url})")
                elif isinstance(decl, str):
                    md.append(f"- {decl}")
            md.append("")

        md.append("")

    return "\n".join(md)

def ensure_directory(path: str) -> None:
    """Ensure that a directory exists."""
    os.makedirs(path, exist_ok=True)

def write_markdown_file(group: str, subgroup: str, content: str) -> None:
    """Write the Markdown content to a file."""
    output_dir = os.path.join(DOCS_OUTPUT_DIR, group)
    ensure_directory(output_dir)

    # Always put files in their group directory
    if subgroup == "_all":
        output_file = os.path.join(output_dir, f"{group}-options.md")
    else:
        output_file = os.path.join(output_dir, f"{subgroup}-options.md")

    with open(output_file, 'w') as f:
        f.write(content)

    print(f"Generated: {output_file}")

def main() -> None:
    """Main function to generate all documentation."""
    # Generate the options JSON file
    import subprocess
    print("Generating options JSON...")
    subprocess.run(["nix", "build", ".#options-doc", "-L", "--accept-flake-config"], check=True)
    
    print("Loading options from JSON...")
    options = load_options()

    print("Categorizing options...")
    categorized = categorize_options(options)

    print("Generating Markdown files...")
    for group, subgroups in categorized.items():
        for subgroup, options_list in subgroups.items():
            if options_list:  # Only generate files for non-empty option lists
                content = generate_markdown(group, subgroup, options_list)
                write_markdown_file(group, subgroup, content)

    print("Documentation generation complete!")

if __name__ == "__main__":
    main()