nix-flake/modules/docs.nix

{ inputs, self, ... }: let
  mkDocsDerivation = { pkgs, doBuild ? true }: let
    inherit (pkgs) lib stdenv mkdocs python314Packages;

    indexMd = let
      rawText = ''
        ## Welcome!
        This site is rebuilt with every generation, and holds a complete record of all options declared within this flake.
      '';
    in pkgs.runCommand "index.md" {} ''
      echo "${rawText}" >> $out
    '';

    mkOptionsDocFromModule = commandName: module: let
      eval = lib.evalModules {
        modules = [ module ];
        args = { inherit pkgs; };
      };

      optionsDoc = pkgs.nixosOptionsDoc {
        options = builtins.removeAttrs eval.options ["_module"];
      };
    in pkgs.runCommand commandName {} ''
      cat ${optionsDoc.optionsCommonMark} >> $out
    '';

    nixos-global-options = mkOptionsDocFromModule "nixos-global-options.md" self.nixosModules.globalOptions;
    nixos-graphics-options = mkOptionsDocFromModule "nixos-graphics-options.md" self.nixosModules.graphicsOptions;
    nixos-gaming-options = mkOptionsDocFromModule "nixos-gaming-options.md" self.nixosModules.gamingOptions;

    home-global-options = mkOptionsDocFromModule "home-global-options.md" self.homeModules.globalOptions;
    home-audio-options = mkOptionsDocFromModule "home-audio-options.md" self.homeModules.audioOptions;
    home-graphics-options = mkOptionsDocFromModule "home-graphics-options.md" self.homeModules.graphicsOptions;
    home-gaming-options = mkOptionsDocFromModule "home-gaming-options.md" self.homeModules.gamingOptions;

    mkDocsConfig = ''
      site_name: flake options
      nav:
        - Home: 'index.md'
        - Options:
          - NixOS: 
            - Global: 'nixos-global-options.md'
            - Capabilities:
              - Graphics: 'nixos-graphics-options.md'
              - Gaming: 'nixos-gaming-options.md'
          - Home Manager:
            - Global: 'home-global-options.md'
            - Capabilities:
              - Audio: 'home-audio-options.md'
              - Graphics: 'home-graphics-options.md'
              - Gaming: 'home-gaming-options.md'
      theme:
        name: material
        palette:
          scheme: slate
      markdown_extensions:
        - admonition
        - pymdownx.details
        - pymdownx.superfences
    '';

    mkDocsYml = pkgs.runCommand "mkdocs.yml" {} ''
      echo "${mkDocsConfig}" >> $out
    '';
  in stdenv.mkDerivation {
    unpackPhase = "true";
    name = if doBuild then "docs" else "docs-md";
    buildInput = [
      mkDocsYml
      indexMd
      nixos-global-options
      nixos-graphics-options
      nixos-gaming-options
      home-global-options
      home-audio-options
      home-graphics-options
      home-gaming-options
    ];
    nativeBuildInputs = [
      mkdocs
      python314Packages.mkdocs-material
      python314Packages.pygments
    ];
    buildPhase = ''
      mkdir docs-build
      cd docs-build
      ln -s ${mkDocsYml} "./mkdocs.yml"
      mkdir docs
      ln -s ${indexMd} "./docs/index.md"
      ln -s ${nixos-global-options} "./docs/nixos-global-options.md"
      ln -s ${nixos-graphics-options} "./docs/nixos-graphics-options.md"
      ln -s ${nixos-gaming-options} "./docs/nixos-gaming-options.md"
      ln -s ${home-global-options} "./docs/home-global-options.md"
      ln -s ${home-audio-options} "./docs/home-audio-options.md"
      ln -s ${home-graphics-options} "./docs/home-graphics-options.md"
      ln -s ${home-gaming-options} "./docs/home-gaming-options.md"
      # generate the site
      ${if doBuild then "mkdocs build" else ""}
    '';
    installPhase = if doBuild then ''
      mv site $out
    '' else ''
      cp -r . $out
    '';
  };

  containerAttrs = { pkgs, port }: {
    image = "docker.io/library/nginx:latest";
    volumes = [
      "${mkDocsDerivation { inherit pkgs; }}:/usr/share/nginx/html"
    ];
    ports = [
      "${port}:80"
    ];
  };
in {
  imports = [ (inputs.helpers.mkMirroredModulesFlakeModule "graphicsOptions" ({ lib, ... }: {
    options.features.documentation = let
      defaultPort = "8080";
    in {
      enable = lib.mkOption {
        type = lib.types.bool;
        description = "Whether to enable documentation for the flake, generated with [Material for mkDocs](https://squidfunk.github.io/mkdocs-material/) and hosted by (containerised) nginx at localhost:${defaultPort} by default.";
        default = true;
      };

      port = lib.mkOption {
        type = lib.types.str;
        description = "This option sets the port used by the nginx server hosting the local documentation site.";
        default = defaultPort;
        readOnly = true;
      };
    };
  })) ];

  perSystem = { pkgs, ... }: {
    packages.docs = mkDocsDerivation { inherit pkgs; };
    packages.docs-md = mkDocsDerivation { inherit pkgs; doBuild = false; };
  };

  flake.nixosModules.graphics = { pkgs, config, lib, ... }: {
    config = (inputs.helpers.mkIfElse (config.features.nixos.home-manager.enable) {
      home-manager.users.${config.info.userName}.features.documentation = lib.mkDefault config.features.documentation;
    } {
      virtualisation.oci-containers = lib.mkIf (config.features.documentation.enable) {
        backend = "docker";
        containers.flake-docs-nginx = containerAttrs { inherit (config.features.documentation) port; inherit pkgs; };
      };
    });
  };

  flake.homeModules.graphics = { pkgs, config, lib, ... }: {
    services.podman = lib.mkIf (config.features.documentation.enable) {
      enable = true;
      containers.flake-docs-nginx = containerAttrs { inherit (config.features.documentation) port; inherit pkgs; };
    };
  };
}