provisioning/tools/distribution/generate-docs.nu

#!/usr/bin/env nu

# Documentation generation tool - generates distribution documentation
#
# Generates:
# - Installation guides and system requirements
# - User manuals and API documentation
# - Configuration references and examples
# - Troubleshooting guides and FAQ
# - Developer documentation and contributing guides

use std log
use ./docs_discovery.nu
use ./guide_generators.nu
use ./docs_templates.nu
use ./docs_postprocessing.nu

def main [--source-root: string = "", --output-dir: string = "dist/docs", --doc-types: string = "all", --format: string = "markdown", --include-examples = true, --generate-api = true, --create-index = true, --minify-output = false, --verbose] {

    let repo_root = if $source_root == "" {
        ($env.PWD | path dirname | path dirname | path dirname)
    } else {
        ($source_root | path expand)
    }

    let doc_types_list = if $doc_types == "all" {
        ["user", "admin", "dev", "api"]
    } else {
        ($doc_types | split row "," | each { str trim })
    }

    let format_list = if $format == "all" {
        ["markdown", "html"]
    } else {
        [$format]
    }

    let docs_config = {
        source_root: $repo_root
        output_dir: ($output_dir | path expand)
        doc_types: $doc_types_list
        formats: $format_list
        include_examples: $include_examples
        generate_api: $generate_api
        create_index: $create_index
        minify_output: $minify_output
        verbose: $verbose
    }

    log info $"Starting documentation generation with config: ($docs_config)"

    # Ensure output directory exists
    mkdir ($docs_config.output_dir)

    let generation_results = []

    let result = (do {
        # Phase 1: Discover documentation sources
        let discovery_result = discover-all-docs $docs_config

        let generation_results = ($generation_results | append { phase: "discovery", result: $discovery_result })

        # Phase 2: Generate user documentation
        let user_docs_result = if "user" in $docs_config.doc_types {
            generate_user_documentation $docs_config $discovery_result
        } else {
            { status: "skipped", reason: "user documentation not requested" }
        }

        let generation_results = ($generation_results | append { phase: "user", result: $user_docs_result })

        # Phase 3: Generate admin documentation
        let admin_docs_result = if "admin" in $docs_config.doc_types {
            generate_admin_documentation $docs_config $discovery_result
        } else {
            { status: "skipped", reason: "admin documentation not requested" }
        }

        let generation_results = ($generation_results | append { phase: "admin", result: $admin_docs_result })

        # Phase 4: Generate developer documentation
        let dev_docs_result = if "dev" in $docs_config.doc_types {
            generate_developer_documentation $docs_config $discovery_result
        } else {
            { status: "skipped", reason: "developer documentation not requested" }
        }

        let generation_results = ($generation_results | append { phase: "dev", result: $dev_docs_result })

        # Phase 5: Generate API documentation
        let api_docs_result = if "api" in $docs_config.doc_types and $docs_config.generate_api {
            generate_api_documentation $docs_config $discovery_result
        } else {
            { status: "skipped", reason: "API documentation not requested or disabled" }
        }

        let generation_results = ($generation_results | append { phase: "api", result: $api_docs_result })

        # Phase 6: Create documentation index
        let index_result = if $docs_config.create_index {
            create_documentation_index $docs_config $generation_results
        } else {
            { status: "skipped", reason: "index creation disabled" }
        }

        let generation_results = ($generation_results | append { phase: "index", result: $index_result })

        # Phase 7: Convert to additional formats
        let conversion_result = convert_documentation_formats $docs_config $generation_results

        let generation_results = ($generation_results | append { phase: "conversion", result: $conversion_result })

        let summary = {
            source_root: $docs_config.source_root
            output_directory: $docs_config.output_dir
            doc_types: ($docs_config.doc_types | length)
            formats: ($docs_config.formats | length)
            successful_phases: ($generation_results | where {|r| $r.result.status == "success"} | length)
            total_phases: ($generation_results | length)
            documents_generated: (count_generated_documents $generation_results)
            total_size: (get_directory_size $docs_config.output_dir)
            docs_config: $docs_config
            phases: $generation_results
        }

        log info $"Documentation generation completed - ($summary.documents_generated) documents generated"

        $summary
    } | complete)

    if $result.exit_code != 0 {
        log error $"Documentation generation failed: ($result.stderr)"
        exit 1
    }

    $result.stdout
}

# Show documentation generation status
def "main status" [] {
    let repo_root = ($env.PWD | path dirname | path dirname | path dirname)

    # Check for documentation sources
    let existing_docs = find-existing-docs $repo_root
    let has_readme = (($repo_root | path join "README.md") | path exists)

    {
        repository: $repo_root
        existing_docs: $existing_docs.total_docs
        has_readme: $has_readme
        supported_formats: ["markdown", "html"]
        doc_types: ["user", "admin", "dev", "api"]
        ready_for_generation: true
    }
}

# Quick documentation generation with minimal options
def "main quick" [
    --output-dir: string = "dist/docs"          # Output directory
    --doc-types: string = "user"                # Documentation types
] {
    main --output-dir $output_dir --doc-types $doc_types --format markdown
}