docs: improve module reference rendering

nix-community · Oct 11, 2023 · af64cc5 · af64cc5
1 parent 585b98c
commit af64cc5
Show file tree

Hide file tree

Showing 8 changed files with 99 additions and 64 deletions.
diff --git a/...s/dream2nix/derivation-common/options.nix → ...-derivation/derivation-common/options.nix b/...s/dream2nix/derivation-common/options.nix → ...-derivation/derivation-common/options.nix
diff --git a/modules/dream2nix/builtins-derivation/interface.nix b/modules/dream2nix/builtins-derivation/interface.nix
@@ -6,7 +6,7 @@
   l = lib // builtins;
   t = l.types;
 
-  common-options = import ../derivation-common/options.nix {inherit lib;};
+  common-options = import ./derivation-common/options.nix {inherit lib;};
 
   builtin-derivation-options = {
     # basic arguments

diff --git a/modules/dream2nix/core/lock/default.nix b/modules/dream2nix/core/lock/default.nix
@@ -191,6 +191,8 @@
 in {
   imports = [
     ./interface.nix
+    ../assertions.nix
+    ../deps
   ];
 
   config = {

diff --git a/modules/dream2nix/mkDerivation/implementation.nix b/modules/dream2nix/mkDerivation/implementation.nix
@@ -60,4 +60,8 @@ in {
       inherit (config.public) version;
       pname = config.name;
     };
+
+  config.deps = {nixpkgs, ...}: {
+    stdenv = lib.mkOverride 1050 nixpkgs.stdenv;
+  };
 }
diff --git a/modules/dream2nix/mkDerivation/interface.nix b/modules/dream2nix/mkDerivation/interface.nix
@@ -8,7 +8,7 @@
   l = lib // builtins;
   t = l.types;
 
-  common-options = import ../derivation-common/options.nix {inherit lib;};
+  common-options = import ../builtins-derivation/derivation-common/options.nix {inherit lib;};
 
   derivationType = t.oneOf [t.str t.path t.package];
 

diff --git a/modules/flake-parts/render/default.nix b/modules/flake-parts/render/default.nix
@@ -71,13 +71,20 @@ in {
     };
 
     eval = evalWith {
-      modules = concatLists (mapAttrsToList (name: inputCfg: inputCfg.getModules inputCfg.flake) cfg.inputs);
+      modules = concatLists (mapAttrsToList (name: inputCfg: [inputCfg.module]) cfg.inputs);
     };
     evalWith = {modules}:
       lib.evalModules {
-        modules = modules;
-        specialArgs.dream2nix.modules = self.modules;
-        specialArgs.packageSets = {};
+        modules =
+          modules
+          ++ [
+            # {
+            #   name = "dummy-name";
+            #   version = "dummy-version";
+            # }
+          ];
+        specialArgs.dream2nix = self;
+        specialArgs.packageSets.nixpkgs = pkgs;
       };
     # inputs.flake-parts.lib.evalFlakeModule
     # {
@@ -123,44 +130,40 @@ in {
               in [
                 {
                   url = baseUrl + subpath;
-                  name = sourceName + subpath;
+                  name = "dream2nix" + subpath;
                 }
               ]
               else []
           )
           opt.declarations;
       in
-        # if
-        #   declarations
-        #   == []
-        #   || (
-        #     # sourceName != "flake-parts" && coreOptDecls ? ${lib.showOption opt.loc}
-        #     sourceName != "flake-parts"
-        #   )
-        # then opt // {visible = false;}
-        # else opt // {inherit declarations;};
-        opt // {inherit declarations;};
+        if
+          declarations
+          == []
+          || (
+            (lib.head opt.loc) != sourceName
+          )
+        then opt // {visible = false;}
+        else opt // {inherit declarations;};
 
     inputModule = {
       config,
       name,
       ...
     }: {
       options = {
-        flake = mkOption {
+        module = mkOption {
           type = types.raw;
           description = ''
-            A flake.
+            A Module.
           '';
-          default = inputs.${name};
         };
 
         sourcePath = mkOption {
           type = types.path;
           description = ''
             Source path in which the modules are contained.
           '';
-          default = config.flake.outPath;
         };
 
         title = mkOption {
@@ -224,29 +227,13 @@ in {
           default = ''
             ## Installation
 
-            ${
-              if config.installationDeclareInput
-              then ''
-                To use these options, add to your flake inputs:
-
-                ```nix
-                ${config.sourceName}.url = "${config.flakeRef}";
-                ```
-
-                and inside the `mkFlake`:
-              ''
-              else ''
-                To use these options, add inside the `mkFlake`:
-              ''
-            }
+            To import this module into your dream2nix package:
 
             ```nix
             imports = [
-              inputs.${config.sourceName}.${lib.concatMapStringsSep "." lib.strings.escapeNixIdentifier config.attributePath}
+              ${lib.concatMapStringsSep "." lib.strings.escapeNixIdentifier config.attributePath}
             ];
             ```
-
-            Run `nix flake lock` and you're set.
           '';
         };
 
@@ -265,19 +252,6 @@ in {
           '';
         };
 
-        getModules = mkOption {
-          type = types.functionTo (types.listOf types.raw);
-          description = ''
-            Get the modules to render.
-          '';
-          default = flake: [
-            (
-              builtins.addErrorContext "while getting modules for input '${name}'"
-              (lib.getAttrFromPath config.attributePath flake)
-            )
-          ];
-        };
-
         attributePath = mkOption {
           type = types.listOf types.str;
           description = ''
@@ -325,7 +299,7 @@ in {
             if config.separateEval
             then
               (evalWith {
-                modules = config.getModules config.flake;
+                modules = [config.module];
               })
               .options
             else opts;
@@ -334,7 +308,7 @@ in {
             inherit (config) sourceName baseUrl sourcePath;
             # inherit coreOptDecls;
           };
-          warningsAreErrors = true; # not sure if feasible long term
+          warningsAreErrors = false; # not sure if feasible long term
           markdownByDefault = true;
         };
         rendered =
@@ -375,6 +349,20 @@ in {
         })
         cfg.inputs
         // {
+          # generate markdown file like:
+          # Summary
+          # - [Reference Documentation]()
+          #   - [core (built in)](./options/core.md)
+          generated-summary-md = pkgs.writeText "SUMMARY.md" ''
+            # Summary
+            - [Reference Documentation]()
+            ${
+              lib.concatStringsSep "\n"
+              (lib.mapAttrsToList
+                (name: inputCfg: "  - [${inputCfg.sourceName}](./options/${name}.md)")
+                cfg.inputs)
+            }
+          '';
           generated-docs =
             pkgs.runCommand "generated-docs"
             {

diff --git a/modules/flake-parts/site/default.nix b/modules/flake-parts/site/default.nix
@@ -26,7 +26,7 @@
       pkgs.runCommand "linkcheck"
       {
         nativeBuildInputs = [pkgs.linkchecker pkgs.python3];
-        site = config.packages.default;
+        site = config.packages.website;
       } ''
         # https://linkchecker.github.io/linkchecker/man/linkcheckerrc.html
         cat >>$TMPDIR/linkcheckrc <<EOF
@@ -52,6 +52,7 @@
           runHook preBuild
 
           cp ${self + /docs/theme/highlight.js} ./src/highlight.js
+          cp ${self'.packages.generated-summary-md} ./src/SUMMARY.md
           mkdir -p ./theme
           cp ${self + /modules/dream2nix/core/docs/theme/favicon.png} ./theme/favicon.png
 
@@ -77,7 +78,8 @@
           cp -r $TMPDIR/out/html $out
           cp _redirects $out
 
-          echo '<html><head><script>window.location.pathname = window.location.pathname.replace(/options.html$/, "") + "options/flake-parts.html"</script></head><body><a href="options/flake-parts.html">to the options</a></body></html>' \
+          # TODO: point to something else than public.html
+          echo '<html><head><script>window.location.pathname = window.location.pathname.replace(/options.html$/, "") + "options/public.html"</script></head><body><a href="options/public.html">to the options</a></body></html>' \
             >$out/options.html
 
           runHook postBuild

diff --git a/modules/flake-parts/website.nix b/modules/flake-parts/website.nix
@@ -10,15 +10,54 @@
     pkgs,
     ...
   }: {
-    render.inputs = {
-      core = {
-        title = "core";
-        flake.module = self.modules.dream2nix.core;
-        flake.outPath = self;
-        attributePath = ["module"];
+    render.inputs =
+      lib.flip lib.mapAttrs
+      (lib.filterAttrs (name: module:
+        lib.elem name [
+          # "buildPythonPackage"
+          # "buildRustPackage"
+          # "builtins-derivation"
+          # "core"
+          # "groups"
+          # "mkDerivation"
+          # "mkDerivation-sane-defaults"
+          # "nixpkgs-overrides"
+          # "nodejs-devshell"
+          # "nodejs-granular"
+          # "nodejs-granular-v3"
+          # "nodejs-node-modules"
+          # "nodejs-package-json"
+          # "nodejs-package-lock"
+          # "nodejs-package-lock-v3"
+          # "package-func"
+          # "php-composer-lock"
+          # "php-granular"
+          # "pip"
+          # "pip-hotfixes"
+          # "rust-cargo-lock"
+          # "rust-crane"
+          # "_template"
+          # "WIP-python-pdm"
+          # "WIP-python-pyproject"
+          # "WIP-spago"
+
+          # "lock"
+          "mkDerivation"
+          "public"
+        ]) (self.modules.dream2nix))
+      (name: module: {
+        title = name;
+        module = self.modules.dream2nix.${name};
+        sourcePath = self;
+        attributePath = [
+          "dream2nix"
+          "modules"
+          "dream2nix"
+          (lib.strings.escapeNixIdentifier name)
+        ];
         intro = "intro";
         baseUrl = "https://github.com/nix-community/dream2nix/blob/master";
-      };
-    };
+        separateEval = true;
+      });
   };
 }