Dotnet documentation script

generate-dotnet-project-docs.sh

#!/bin/bash

# Generate comprehensive API documentation for .NET projects using Roslynator
# Author: Martin Alderson (https://martinalderson.com)
# License: MIT License - provided "as is" without warranty of any kind
# Usage: ./generate-docs.sh [project.csproj]

set -euo pipefail

# Configuration
PROJECT=${1:-ConsoleApp.csproj}
DOCS_DIR="docs"
THIRDPARTY_DIR="$DOCS_DIR/thirdparty"

# Get NuGet packages referenced in project
get_project_dlls() {
    local project_file="$1"
    
    # Extract PackageReference names and versions from csproj
    grep -o 'PackageReference Include="[^"]*" Version="[^"]*"' "$project_file" | \
    while read -r line; do
        local package_name=$(echo "$line" | sed -n 's/.*Include="\([^"]*\)".*/\1/p')
        local version=$(echo "$line" | sed -n 's/.*Version="\([^"]*\)".*/\1/p')
        
        # Convert package name to lowercase for NuGet folder structure
        local package_folder=$(echo "$package_name" | tr '[:upper:]' '[:lower:]')
        
        # Find the DLL in NuGet cache
        find ~/.nuget/packages/"$package_folder"/"$version"/lib -name "*.dll" 2>/dev/null | head -1
    done
}

# Generate API documentation for a DLL
document_dll() {
    local dll_path="$1"
    local output_file="$2"
    
    roslynator list-symbols "$PROJECT" \
        --external-assemblies "$dll_path" \
        --visibility public \
        --depth member \
        > "$output_file" 2>/dev/null
}

main() {
    echo "🔍 Generating documentation for $PROJECT..."
    
    # Clean and create structure
    rm -rf "$DOCS_DIR"
    mkdir -p "$THIRDPARTY_DIR"
    
    # Generate project documentation
    echo "📚 Generating project API documentation..."
    roslynator list-symbols "$PROJECT" \
        --visibility public \
        --depth member \
        > "$DOCS_DIR/project-api.txt"
    
    # Find and document NuGet packages from project references
    echo "📖 Documenting third-party libraries..."
    
    # Get the list of DLLs and process them
    local dll_list=$(get_project_dlls "$PROJECT")
    local documented_count=0
    
    for dll_path in $dll_list; do
        [[ -z "$dll_path" ]] && continue
        if [[ -f "$dll_path" ]]; then
            local package_name=$(basename "$dll_path" .dll)
            local output_file="$THIRDPARTY_DIR/${package_name}-api.txt"
            
            echo "  📦 $package_name..."
            
            if document_dll "$dll_path" "$output_file"; then
                local line_count=$(wc -l < "$output_file" 2>/dev/null || echo "0")
                echo "    ✅ $line_count lines"
                documented_count=$((documented_count + 1))
            else
                echo "    ⚠️  Failed"
            fi
        fi
    done
    
    # Generate summary
    cat > "$DOCS_DIR/README.md" << EOF
# API Documentation

## Project API
- \`project-api.txt\` - All project classes and methods

## Third-party Libraries ($documented_count documented)
$(if [[ $documented_count -gt 0 ]]; then
    ls "$THIRDPARTY_DIR" | sed 's/-api\.txt$//' | sed 's/^/- /'
else
    echo "- None found"
fi)

## Usage
\`\`\`bash
# Search project APIs
grep "MethodName" docs/project-api.txt

# Search third-party APIs  
grep -r "MethodName" docs/thirdparty/

# List all third-party packages
ls docs/thirdparty/
\`\`\`
EOF

    echo "✅ Documentation complete!"
    echo "   📄 Project: $(wc -l < "$DOCS_DIR/project-api.txt") lines"
    echo "   📦 Libraries: $documented_count packages"
    echo "   📁 Output: $DOCS_DIR/"
}

# Only run main if script is executed directly (not sourced)
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main "$@"
fi