homelab/pkgs/homelab-docs

# homelab-docs-readme.nix - README generator CLI
{
  writeShellScriptBin,
  jq,
}:
writeShellScriptBin "homelab-docs-readme" ''
  #!/usr/bin/env bash
  set -euo pipefail

  cat << EOF
  # Homelab Documentation

  > Auto-generated documentation for the homelab deployment
  >
  > Generated on: $(date -R)
  > Source: $(pwd)

  ## 📚 Documentation Files

  This documentation is automatically generated from your colmena flake configuration.

  ### 📊 Overview Documents
  - **[Fleet Overview](fleet-overview.md)** - High-level fleet statistics and service distribution
  - **[Current Deployment](current-deployment.md)** - Current deployment state and node status

  ### 📖 Detailed Configuration
  - **[Node Configurations](nodes.md)** - Per-node detailed configuration and services
  - **[Service Configurations](services.md)** - Service configurations across the fleet

  ## 🚀 Quick Actions

  ### View Current Status
  \`\`\`bash
  # Service status across fleet (if homelab CLI is available)
  homelab services --global

  # Backup status
  homelab backups --global

  # Overall status
  homelab status
  \`\`\`

  ### Update Documentation
  \`\`\`bash
  # Regenerate all documentation
  homelab-generate-docs ./docs

  # Generate in different directory
  homelab-generate-docs /path/to/output
  \`\`\`

  ## 📋 Quick Stats

  EOF

  # Add live stats
  quick_stats=$(colmena eval -E '{ nodes, pkgs, lib, ... }:
    let
      homelabNodes = lib.filterAttrs (name: node: node.config.homelab.enable or false) nodes;
    in {
      totalNodes = lib.length (lib.attrNames nodes);
      homelabNodes = lib.length (lib.attrNames homelabNodes);
    }')

  total_nodes=$(echo "$quick_stats" | ${jq}/bin/jq -r '.totalNodes')
  homelab_nodes=$(echo "$quick_stats" | ${jq}/bin/jq -r '.homelabNodes')

  echo "- **Total Nodes**: $total_nodes"
  echo "- **Homelab-Enabled Nodes**: $homelab_nodes"
  echo "- **Generated**: $(date -R)"
  echo
  echo "## 🛠️ Management Tools"
  echo
  echo "### Documentation Commands"
  echo "- \`homelab-generate-docs\` - Regenerate this documentation"
  echo "- \`homelab-docs-fleet\` - Generate fleet overview only"
  echo "- \`homelab-docs-nodes\` - Generate node configurations only"
  echo "- \`homelab-docs-services\` - Generate service configurations only"
  echo "- \`homelab-docs-deployment\` - Generate deployment state only"
  echo
  echo "### Colmena Commands"
  echo "- \`colmena eval\` - Evaluate flake expressions"
  echo "- \`colmena apply\` - Deploy configuration changes"
  echo "- \`colmena build\` - Build configurations without deploying"
  echo
  echo "## 🎯 Integration with CI/CD"
  echo
  echo "### GitHub Actions Example"
  echo
  echo "\`\`\`yaml"
  echo "name: Generate Documentation"
  echo "on:"
  echo "  push:"
  echo "    branches: [ main ]"
  echo ""
  echo "jobs:"
  echo "  docs:"
  echo "    runs-on: ubuntu-latest"
  echo "    steps:"
  echo "    - uses: actions/checkout@v4"
  echo "    - uses: cachix/install-nix-action@v24"
  echo "    - name: Generate docs"
  echo "      run: nix develop --command homelab-generate-docs ./docs"
  echo "    - name: Commit docs"
  echo "      run: |"
  echo "        git add docs/"
  echo "        git commit -m \"docs: update homelab documentation\" || exit 0"
  echo "        git push"
  echo "\`\`\`"
  echo
  echo "### Manual Generation"
  echo
  echo "\`\`\`bash"
  echo "# From your homelab directory"
  echo "nix develop"
  echo "homelab-generate-docs ./docs"
  echo "git add docs/ && git commit -m \"Update docs\""
  echo "\`\`\`"
  echo
  echo "---"
  echo
  echo "*This documentation reflects the live state of your homelab deployment as evaluated by colmena.*"
''