From 064ba88cdf6ce391cdbe3e4df72363276dbb5ebd Mon Sep 17 00:00:00 2001
From: Pacman99 <pachum99@gmail.com>
Date: Mon, 26 Apr 2021 21:38:27 -0700
Subject: [PATCH] improve, build, and add mkFlake options doc

---
 doc/mkFlakeOptions.md    | 407 +++++++++++++++++++++++++++++++++++++++
 lib/mkFlake/evalArgs.nix |  25 ++-
 2 files changed, 425 insertions(+), 7 deletions(-)
 create mode 100644 doc/mkFlakeOptions.md

diff --git a/doc/mkFlakeOptions.md b/doc/mkFlakeOptions.md
new file mode 100644
index 00000000..42b1f60f
--- /dev/null
+++ b/doc/mkFlakeOptions.md
@@ -0,0 +1,407 @@
+## channels
+nixpkgs channels to create
+
+
+*_Type_*:
+attribute set of submodules
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## channels.\<name\>.config
+nixpkgs config for this channel
+
+
+*_Type_*:
+attribute set or path convertible to it
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## channels.\<name\>.input
+nixpkgs flake input to use for this channel
+
+
+*_Type_*:
+nix flake
+
+
+*_Default_*
+```
+"inputs.\\<name\\>"
+```
+
+
+
+
+## channels.\<name\>.overlays
+overlays to apply to this channel
+these will get exported under the 'overlays' flake output
+as \<channel\>/\<name\> and any overlay pulled from ${inputs}
+will be filtered out
+
+
+*_Type_*:
+list of valid Nixpkgs overlay or path convertible to its or path convertible to it
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## channelsConfig
+nixpkgs config for all channels
+
+
+*_Type_*:
+attribute set or path convertible to it
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## home
+hosts, modules, suites, and profiles for home-manager
+
+
+*_Type_*:
+submodule
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## home.externalModules
+modules to include that won't be exported
+meant importing modules from external flakes
+
+
+*_Type_*:
+list of valid module or path convertible to its
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## home.modules
+modules to include in all hosts and export to homeModules output
+
+
+*_Type_*:
+list of paths or path convertible to it
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## home.profiles
+profile folders that can be collected into suites
+the name of the argument passed to suites is based
+on the folder name.
+[ ./profiles ] => { profiles }:
+
+
+*_Type_*:
+list of paths
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## home.suites
+Function that takes profiles and returns suites for this config system
+These can be accessed through the 'suites' special argument.
+
+
+*_Type_*:
+function that evaluates to a(n) attrs or path convertible to it
+
+
+*_Default_*
+```
+"<function>"
+```
+
+
+
+
+## inputs
+inputs for this flake
+used to set channel defaults and create registry
+
+
+*_Type_*:
+attribute set of nix flakes
+
+
+
+
+
+
+## nixos
+hosts, modules, suites, and profiles for nixos
+
+
+*_Type_*:
+submodule
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## nixos.hostDefaults
+Defaults for all hosts.
+the modules passed under hostDefaults will be exported
+to the 'nixosModules' flake output.
+They will also be added to all hosts.
+
+
+*_Type_*:
+submodule
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## nixos.hostDefaults.channelName
+Channel this host should follow
+
+
+*_Type_*:
+a channel defined in `channels`
+
+
+*_Default_*
+```
+null
+```
+
+
+
+
+## nixos.hostDefaults.externalModules
+modules to include that won't be exported
+meant importing modules from external flakes
+
+
+*_Type_*:
+list of valid module or path convertible to its
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## nixos.hostDefaults.modules
+modules to include in all hosts and export to nixosModules output
+
+
+*_Type_*:
+list of paths or path convertible to it
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## nixos.hostDefaults.system
+system for this host
+
+
+*_Type_*:
+system defined in `supportedSystems`
+
+
+*_Default_*
+```
+null
+```
+
+
+
+
+## nixos.hosts
+configurations to include in the nixosConfigurations output
+
+
+*_Type_*:
+attribute set of submodules
+
+
+*_Default_*
+```
+{}
+```
+
+
+
+
+## nixos.hosts.\<name\>.channelName
+Channel this host should follow
+
+
+*_Type_*:
+a channel defined in `channels`
+
+
+*_Default_*
+```
+null
+```
+
+
+
+
+## nixos.hosts.\<name\>.modules
+modules to include
+
+
+*_Type_*:
+list of valid module or path convertible to its or valid module or path convertible to it convertible to it
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## nixos.hosts.\<name\>.system
+system for this host
+
+
+*_Type_*:
+system defined in `supportedSystems`
+
+
+*_Default_*
+```
+null
+```
+
+
+
+
+## nixos.profiles
+profile folders that can be collected into suites
+the name of the argument passed to suites is based
+on the folder name.
+[ ./profiles ] => { profiles }:
+
+
+*_Type_*:
+list of paths
+
+
+*_Default_*
+```
+[]
+```
+
+
+
+
+## nixos.suites
+Function that takes profiles and returns suites for this config system
+These can be accessed through the 'suites' special argument.
+
+
+*_Type_*:
+function that evaluates to a(n) attrs or path convertible to it
+
+
+*_Default_*
+```
+"<function>"
+```
+
+
+
+
+## self
+The flake to create the devos outputs for
+
+*_Type_*:
+nix flake
+
+
+
+
+
+
+## supportedSystems
+The systems supported by this flake
+
+
+*_Type_*:
+list of strings
+
+
+*_Default_*
+```
+["aarch64-linux","i686-linux","x86_64-darwin","x86_64-linux"]
+```
+
+
+
diff --git a/lib/mkFlake/evalArgs.nix b/lib/mkFlake/evalArgs.nix
index 1a15dc8e..55b37950 100644
--- a/lib/mkFlake/evalArgs.nix
+++ b/lib/mkFlake/evalArgs.nix
@@ -56,7 +56,9 @@ let
             default = [ ];
             description = escape [ "<" ">" ] ''
               overlays to apply to this channel
-              these will get exported under the 'overlays' flake output as <channel>/<name>
+              these will get exported under the 'overlays' flake output
+              as <channel>/<name> and any overlay pulled from ''\${inputs}
+              will be filtered out
             '';
           };
           config = mkOption {
@@ -74,14 +76,18 @@ let
         options = with types; {
           # anything null in hosts gets filtered out by mkFlake
           system = mkOption {
-            type = nullOr systemType;
+            type = (nullOr systemType) // {
+              description = "system defined in `supportedSystems`";
+            };
             default = null;
             description = ''
               system for this host
             '';
           };
           channelName = mkOption {
-            type = nullOr (types.enum (builtins.attrNames config.channels));
+            type = (nullOr (types.enum (builtins.attrNames config.channels))) // {
+              description = "a channel defined in `channels`";
+            };
             default = null;
             description = ''
               Channel this host should follow
@@ -98,7 +104,8 @@ let
             type = with types; listOf moduleType;
             default = [ ];
             description = ''
-              The configuration for this host
+              modules to include that won't be exported
+              meant importing modules from external flakes
             '';
           };
         };
@@ -168,7 +175,12 @@ let
           profiles = mkOption {
             type = listOf path;
             default = [ ];
-            description = "path to profiles folder that can be collected into suites";
+            description = ''
+              profile folders that can be collected into suites
+              the name of the argument passed to suites is based
+              on the folder name.
+              [ ./profiles ] => { profiles }:
+            '';
           };
           suites = mkOption {
             type = pathTo (functionTo attrs);
@@ -178,8 +190,7 @@ let
               inherit (config) profiles;
             };
             description = ''
-              Function with the input of 'profiles' that returns an attribute set
-              with the suites for this config system.
+              Function that takes profiles and returns suites for this config system
               These can be accessed through the 'suites' special argument.
             '';
           };