athenix/parts/docs.nix

# Documentation generation
{
  inputs,
  self,
  lib,
  ...
}:
let
  pkgs = inputs.nixpkgs.legacyPackages.x86_64-linux;

  # Extract options from a sample configuration
  getAthenixOptions =
    configName:
    let
      nixosConfig = self.nixosConfigurations.${configName};
      evaledOptions = nixosConfig.options;

      # Filter to just athenix namespace
      athenixOptions = evaledOptions.athenix or { };
    in
    athenixOptions;

  # Generate wiki home page
  wikiHome = pkgs.writeText "Home.md" ''
    # Athenix - NixOS Fleet Management

    Athenix is a NixOS configuration system for managing the UGA Innovation Factory's fleet of devices using Nix flakes and a custom configuration framework.

    ## Quick Start

    - [Configuration Options](Configuration-Options) - All available `athenix.*` options
    - [User Guide](User-Configuration) - Setting up user accounts and dotfiles
    - [Building](Building) - Creating installers and system images
    - [Development](Development) - Contributing to Athenix

    ## Features

    - **Inventory-based fleet management** - Define entire device fleets in a single file
    - **Multiple hardware types** - Desktops, laptops, Surface tablets, LXC containers, WSL
    - **Flexible software configurations** - Desktop, headless, kiosk, and builder modes
    - **External module support** - Load user dotfiles and system configs from Git repos
    - **Declarative everything** - Reproducible builds with pinned dependencies

    ## Software Types

    Enable different system configurations:

    - **desktop** - Full KDE Plasma 6 desktop environment
    - **headless** - Minimal server/container configuration
    - **tablet-kiosk** - Touch-optimized kiosk for Surface tablets
    - **stateless-kiosk** - Diskless PXE boot kiosk
    - **builders** - CI/CD build server with Gitea Actions runner

    ## Hardware Types

    - **nix-desktop** - Desktop workstations
    - **nix-laptop** - Laptop computers
    - **nix-surface** - Microsoft Surface Pro tablets
    - **nix-lxc** - LXC containers (Proxmox)
    - **nix-wsl** - Windows Subsystem for Linux
    - **nix-ephemeral** - Stateless systems (PXE boot)

    ## Documentation

    Browse the documentation using the sidebar or start with:

    - [README](README) - Repository overview and getting started
    - [Configuration Options](Configuration-Options) - Complete option reference
    - [Inventory Guide](Inventory) - Managing the device fleet
    - [External Modules](External-Modules) - Using external configurations
  '';

  # Generate markdown documentation from options
  optionsToMarkdown =
    options:
    pkgs.writeText "options.md" ''
      # Configuration Options

      This document describes all available configuration options in the Athenix namespace.

      ## Quick Reference

      - **athenix.sw** - Software configuration (desktop, headless, kiosk modes)
      - **athenix.users** - User account management
      - **athenix.host** - Host-specific settings (filesystem, build methods)
      - **athenix.fleet** - Fleet inventory definitions
      - **athenix.forUser** - Convenience option to enable a user
      - **athenix.system.gc** - Garbage collection settings

      ## Detailed Options

      For detailed option information, use:
      ```bash
      # View all athenix options
      nix eval .#nixosConfigurations.nix-desktop1.options.athenix --apply builtins.attrNames

      # View specific option description
      nix eval .#nixosConfigurations.nix-desktop1.options.athenix.sw.desktop.enable.description

      # Export all options to JSON
      nix build .#athenix-options
      cat result | jq
      ```

      ## Software Types

      Enable different system configurations:

      - **desktop** - Full KDE Plasma desktop environment
      - **headless** - Server/container configuration  
      - **tablet-kiosk** - Touch-optimized kiosk for tablets
      - **stateless-kiosk** - Diskless PXE boot kiosk
      - **builders** - Build server with optional Gitea Actions runner

      See the individual option descriptions for detailed information.
    '';
in
{
  perSystem =
    { system, ... }:
    lib.mkIf (system == "x86_64-linux") {
      packages = {
        # Generate option documentation in markdown
        docs =
          pkgs.runCommand "athenix-docs"
            {
              nativeBuildInputs = [ pkgs.jq ];
            }
            ''
              mkdir -p $out

              # Generate wiki home page
              cat > $out/Home.md << 'EOF'
              ${builtins.readFile wikiHome}
              EOF

              # Copy main README
              cp ${../README.md} $out/README.md

              # Copy documentation with wiki-friendly names
              cp ${../docs/BUILDING.md} $out/Building.md
              cp ${../docs/DEVELOPMENT.md} $out/Development.md
              cp ${../docs/EXTERNAL_MODULES.md} $out/External-Modules.md
              cp ${../docs/INVENTORY.md} $out/Inventory.md
              cp ${../docs/NAMESPACE.md} $out/Namespace.md
              cp ${../docs/USER_CONFIGURATION.md} $out/User-Configuration.md

              # Generate options reference
              cat > $out/Configuration-Options.md << 'EOF'
              ${builtins.readFile (optionsToMarkdown (getAthenixOptions "nix-desktop1"))}
              EOF

              echo "Documentation generated in $out"
            '';

        # Extract just the athenix namespace options as JSON
        athenix-options =
          let
            nixosConfig =
              self.nixosConfigurations.nix-desktop1
                or (builtins.head (builtins.attrValues self.nixosConfigurations));

            # Recursively extract option information
            extractOption =
              opt:
              if opt ? _type && opt._type == "option" then
                {
                  inherit (opt) description;
                  type = opt.type.description or (opt.type.name or "unknown");
                  default =
                    if opt ? default then
                      if builtins.isAttrs opt.default && opt.default ? _type then "<special>" else opt.default
                    else
                      null;
                  example =
                    if opt ? example then
                      if builtins.isAttrs opt.example && opt.example ? _type then "<special>" else opt.example
                    else
                      null;
                }
              else if builtins.isAttrs opt then
                lib.mapAttrs (name: value: extractOption value) (
                  # Filter out internal attributes
                  lib.filterAttrs (n: _: !lib.hasPrefix "_" n) opt
                )
              else
                null;

            athenixOpts = nixosConfig.options.athenix or { };
          in
          pkgs.writeText "athenix-options.json" (builtins.toJSON (extractOption athenixOpts));
      };
    };
}