website-htmx-rustelo-code/justfiles/docs.just

# Documentation Commands Module
# Commands for generating, building, serving, and managing documentation

# Set shell for commands
set shell := ["bash", "-c"]

# Generate project documentation (default)
generate:
    @echo "📚 Generating documentation..."
    cargo doc --open

# =============================================================================
# SITE INFORMATION COMMANDS
# =============================================================================

# Generate comprehensive site information
info-generate:
    @echo "📚 Generating Rustelo site information..."
    @echo "📋 Analyzing server routes, components, and pages..."
    SITE_INFO_PATH=${SITE_INFO_PATH:-site/info} cargo build --workspace
    @echo "✅ Site information generated in ${SITE_INFO_PATH:-site/info}/"
    @echo "📁 Structure: server/, components/, pages/, automation/"

# Validate generated route documentation
info-validate:
    @echo "🔍 Validating site information..."
    @if [ -f "${SITE_INFO_PATH:-site/info}/server/data.toml" ]; then \
        echo "✅ Server routes documented"; \
    else \
        echo "❌ Server routes missing"; \
    fi
    @if [ -f "${SITE_INFO_PATH:-site/info}/components/data.toml" ]; then \
        echo "✅ Components documented"; \
    else \
        echo "❌ Components documentation missing"; \
    fi
    @if [ -f "${SITE_INFO_PATH:-site/info}/pages/data.toml" ]; then \
        echo "✅ Pages documented"; \
    else \
        echo "❌ Pages documentation missing"; \
    fi
    @if [ -f "${SITE_INFO_PATH:-site/info}/automation/document.md" ]; then \
        echo "✅ Automation guide available"; \
    else \
        echo "❌ Automation guide missing"; \
    fi

# Show site information summary
info-summary:
    @echo "📊 Site Information Summary"
    @echo "========================"
    @if [ -f "${SITE_INFO_PATH:-site/info}/server/summary.md" ]; then \
        echo "📡 Server Routes:"; \
        tail -1 "${SITE_INFO_PATH:-site/info}/server/summary.md" | grep "Total Routes" || echo "  Summary available"; \
    fi
    @if [ -f "${SITE_INFO_PATH:-site/info}/components/summary.md" ]; then \
        echo "🧩 Components:"; \
        tail -1 "${SITE_INFO_PATH:-site/info}/components/summary.md" | grep "Total Components" || echo "  Summary available"; \
    fi
    @if [ -f "${SITE_INFO_PATH:-site/info}/pages/summary.md" ]; then \
        echo "📄 Pages:"; \
        tail -1 "${SITE_INFO_PATH:-site/info}/pages/summary.md" | grep "Total" || echo "  Summary available"; \
    fi
    @echo "🔧 Automation examples: ${SITE_INFO_PATH:-site/info}/automation/"

# Clean generated site information
info-clean:
    @echo "🧹 Cleaning generated site information..."
    @rm -rf "${SITE_INFO_PATH:-site/info}/"
    @echo "✅ Site information cleaned"

# Generate API clients from documentation (future)
clients:
    @echo "🔌 Generating API clients..."
    @echo "📋 This will generate TypeScript, Rust, and Python clients"
    @echo "🚧 Feature coming soon - will use ${SITE_INFO_PATH:-site/info}/server/data.toml"

# Sync routes with Rustelo Manager (future)
manager-sync:
    @echo "🔄 Syncing routes with Rustelo Manager..."
    @echo "📡 This will update manager with latest route information"
    @echo "🚧 Feature coming soon - will use ${SITE_INFO_PATH:-site/info}/ data"

# Validate generated documentation
validate:
    @echo "🔍 Validating generated documentation..."
    @echo "📋 Checking links, references, and completeness"
    @if [ -d "${SITE_INFO_PATH:-site/info}" ]; then \
        echo "✅ Documentation directory exists"; \
        find "${SITE_INFO_PATH:-site/info}" -name "*.md" -exec wc -l {} + | tail -1; \
    else \
        echo "❌ Documentation not found - run 'just docs::info-generate' first"; \
    fi

# Clean and regenerate all documentation
refresh:
    @echo "🔄 Refreshing all documentation..."
    @just info-clean
    @just ../dev::site-info
    @echo "✅ Documentation refreshed"

# =============================================================================
# CARGO DOCUMENTATION COMMANDS
# =============================================================================

# Build cargo documentation with logo assets (Nushell version)
cargo-nu:
    @echo "📚 Building cargo documentation with logo assets (Nushell)..."
    nu {{justfile_directory()}}/scripts/build/build-docs.nu

# Build cargo documentation with logo assets (Bash fallback)
cargo:
    @echo "📚 Building cargo documentation with logo assets (Bash)..."
    {{justfile_directory()}}/scripts/build/build-docs.sh

# Serve documentation
serve:
    @echo "📚 Serving documentation..."
    cargo doc --no-deps
    python3 -m http.server 8000 -d target/doc

# =============================================================================
# MDBOOK DOCUMENTATION COMMANDS
# =============================================================================

# Setup comprehensive documentation system
setup:
    @echo "📚 Setting up documentation system..."
    {{justfile_directory()}}/scripts/setup-docs.sh --full

# Start documentation development server
dev:
    @echo "📚 Starting documentation development server..."
    {{justfile_directory()}}/scripts/docs-dev.sh

# Build documentation with mdBook
build:
    @echo "📚 Building documentation..."
    {{justfile_directory()}}/scripts/build/build-docs.sh

# Build documentation and sync existing content
build-sync:
    @echo "📚 Building documentation with content sync..."
    {{justfile_directory()}}/scripts/build/build-docs.sh --sync

# Watch documentation for changes
watch:
    @echo "📚 Watching documentation for changes..."
    {{justfile_directory()}}/scripts/build/build-docs.sh --watch

# Serve mdBook documentation with auto-open
book:
    @echo "📚 Serving mdBook documentation..."
    mdbook serve --open

# Build mdBook for changes
book-build:
    @echo "📚 Building mdBook for changes..."
    mdbook build

# Watch mdBook for changes
book-watch:
    @echo "📚 Watching mdBook for changes..."
    mdbook watch

# Serve mdBook on specific port
book-port PORT:
    @echo "📚 Serving mdBook on port {{PORT}}..."
    mdbook serve --port {{PORT}} --open

# Check documentation for broken links
check-links:
    @echo "📚 Checking documentation for broken links..."
    mdbook-linkcheck || echo "Note: Install mdbook-linkcheck for link checking"

# =============================================================================
# DOCUMENTATION DEPLOYMENT COMMANDS
# =============================================================================

# Deploy documentation to GitHub Pages
deploy-github:
    @echo "📚 Deploying documentation to GitHub Pages..."
    {{justfile_directory()}}/scripts/deploy-docs.sh github-pages

# Deploy documentation to Netlify
deploy-netlify:
    @echo "📚 Deploying documentation to Netlify..."
    {{justfile_directory()}}/scripts/deploy-docs.sh netlify

# Deploy documentation to Vercel
deploy-vercel:
    @echo "📚 Deploying documentation to Vercel..."
    {{justfile_directory()}}/scripts/deploy-docs.sh vercel

# Build documentation Docker image
docker:
    @echo "📚 Building documentation Docker image..."
    {{justfile_directory()}}/scripts/deploy-docs.sh docker

# Serve documentation locally with nginx
serve-local:
    @echo "📚 Serving documentation locally..."
    {{justfile_directory()}}/scripts/deploy-docs.sh local

# =============================================================================
# DOCUMENTATION UTILITIES
# =============================================================================

# Generate dynamic documentation content (legacy)
generate-legacy:
    @echo "📚 Generating dynamic documentation content..."
    {{justfile_directory()}}/scripts/generate-content.sh

# Clean documentation build files (legacy)
clean-legacy:
    @echo "📚 Cleaning documentation build files..."
    rm -rf book-output
    rm -rf _book
    @echo "Documentation build files cleaned"

# Complete documentation workflow (build, check, serve)
workflow:
    @echo "📚 Running complete documentation workflow..."
    just build-sync
    just check-links
    just serve-local