chore: add initial nixmkdocs setup and improve documentation

.envrc

@@ -1,2 +1,2 @@
-source $(fetchurl https://gitlab.com/rensa-nix/direnv/-/raw/v0.2.0/direnvrc "sha256-PFFxlZWNz/LLuNHA1Zpu2qdC3MF+oukv/TxFj5Utixk=")
+source $(fetchurl https://gitlab.com/rensa-nix/direnv/-/raw/v0.3.0/direnvrc "sha256-u7+KEz684NnIZ+Vh5x5qLrt8rKdnUNexewBoeTcEVHQ=")
 use ren //repo/devShells/default

.gitignore

@@ -0,0 +1,2 @@
+result
+

.nix/repo/docs.nix

@@ -0,0 +1,68 @@
+{inputs, ...}: let
+  inherit (inputs) pkgs devshell doclib;
+
+  roots = [
+    {
+      url = "https://gitlab.com/rensa-nix/devshell/-/blob/main/lib";
+      path = "${inputs.self}/lib";
+    }
+  ];
+  optionsDoc = doclib.mkOptionDocs {
+    module = devshell.modules;
+    inherit roots;
+  };
+  optionsDocs = pkgs.runCommand "options-docs" {} ''
+    mkdir -p $out
+    ln -s ${optionsDoc} $out/options.md
+  '';
+in
+  (doclib.mkDocs {
+    docs."default" = {
+      base = "${inputs.self}";
+      path = "${inputs.self}/docs";
+      material = {
+        enable = true;
+        colors = {
+          primary = "aqua";
+          accent = "blue";
+        };
+        umami = {
+          enable = false;
+          src = "https://analytics.tf/umami";
+          siteId = "";
+          domains = ["devshell.rensa.projects.tf"];
+        };
+      };
+      macros = {
+        enable = true;
+        includeDir = toString optionsDocs;
+      };
+      config = {
+        site_name = "Devshell";
+        repo_name = "rensa-nix/devshell";
+        repo_url = "https://gitlab.com/rensa-nix/devshell";
+        theme = {
+          logo = "images/logo.png";
+          icon.repo = "simple/gitlab";
+          favicon = "images/favicon.png";
+        };
+        nav = [
+          {"Introduction" = "index.md";}
+          {"Options" = "options.md";}
+        ];
+        markdown_extensions = [
+          {
+            "pymdownx.highlight".pygments_lang_class = true;
+          }
+          "pymdownx.inlinehilite"
+          "pymdownx.snippets"
+          "pymdownx.superfences"
+          "pymdownx.escapeall"
+          "fenced_code"
+        ];
+      };
+    };
+  }).packages
+  // {
+    inherit optionsDocs;
+  }

.nix/repo/flake.lock

@@ -1,5 +1,37 @@
 {
   "nodes": {
+    "mkdocs-material-umami": {
+      "locked": {
+        "lastModified": 1745840856,
+        "narHash": "sha256-1Ad1JTMQMP6YsoIKAA+SBCE15qWrYkGue9/lXOLnu9I=",
+        "owner": "technofab",
+        "repo": "mkdocs-material-umami",
+        "rev": "3ac9b194450f6b779c37b8d16fec640198e5cd0a",
+        "type": "gitlab"
+      },
+      "original": {
+        "owner": "technofab",
+        "repo": "mkdocs-material-umami",
+        "type": "gitlab"
+      }
+    },
+    "nixmkdocs": {
+      "locked": {
+        "dir": "lib",
+        "lastModified": 1755783537,
+        "narHash": "sha256-78lWSC3UzkpWYsnyncqbrE37gEIWLzejOeDyoBb6h5o=",
+        "owner": "TECHNOFAB",
+        "repo": "nixmkdocs",
+        "rev": "4fd5a351c54e005c4e8df7e23a8e4eec9d3b8cd1",
+        "type": "gitlab"
+      },
+      "original": {
+        "dir": "lib",
+        "owner": "TECHNOFAB",
+        "repo": "nixmkdocs",
+        "type": "gitlab"
+      }
+    },
     "nixtest-lib": {
       "locked": {
         "dir": "lib",
@@ -19,6 +51,8 @@
     },
     "root": {
       "inputs": {
+        "mkdocs-material-umami": "mkdocs-material-umami",
+        "nixmkdocs": "nixmkdocs",
         "nixtest-lib": "nixtest-lib"
       }
     }

.nix/repo/flake.nix

@@ -1,11 +1,17 @@
 {
   inputs = {
     nixtest-lib.url = "gitlab:TECHNOFAB/nixtest?dir=lib";
+    nixmkdocs.url = "gitlab:TECHNOFAB/nixmkdocs?dir=lib";
+    mkdocs-material-umami.url = "gitlab:technofab/mkdocs-material-umami";
   };
   outputs = i:
     i
     // {
       ntlib = i.nixtest-lib.lib {inherit (i.parent) pkgs;};
+      doclib = i.nixmkdocs.lib {
+        inherit (i.parent) pkgs;
+        inherit (i.parent.pkgs) lib;
+      };
       devshell = import "${i.parent.self}/lib" {inherit (i.parent) pkgs;};
     };
 }

docs/index.md

@@ -0,0 +1 @@
+# Hello world!

docs/options.md

@@ -0,0 +1,3 @@
+# Options
+
+{% include 'options.md' %}

flake.nix

@@ -32,9 +32,14 @@
         (simple "devShells")
         (simple "tests")
         (simple "benchmark")
+        (simple "docs")
       ];
     }
     {
-      packages = ren.select self [["repo" "tests"] ["repo" "benchmark"]];
+      packages = ren.select self [
+        ["repo" "tests"]
+        ["repo" "benchmark"]
+        ["repo" "docs"]
+      ];
     };
 }

lib/default.nix

@@ -3,7 +3,7 @@
   lib ? pkgs.lib,
   ...
 }: rec {
-  modules = import ./modules;
+  modules = ./modules;
   eval = {config, ...}: let
     res = lib.evalModules {
       modules = [config modules];

lib/modules/env.nix

@@ -42,6 +42,23 @@
       name = mkOption {
         type = types.str;
         default = name;
+        description = ''
+          Name of the environment variable, usually already set to `<name>`.
+        '';
+      };
+      desc = mkOption {
+        type = types.nullOr types.str;
+        default = null;
+        description = ''
+          Description of the env var, can be shown in the menu.
+        '';
+      };
+      visible = mkOption {
+        type = types.bool;
+        default = true;
+        description = ''
+          Whether to include this env var and it's description in the menu.
+        '';
       };
       value = mkOption {
         type = with types;
@@ -52,13 +69,18 @@
             package
           ]);
         default = null;
+        example = "hello";
+        description = ''
+          Any value to convert to a string and set the env variable to.
+          There is no evaluation of the value, for that see [eval](#envnameeval).
+        '';
       };
 
       eval = mkOption {
         type = types.nullOr types.str;
         default = null;
         description = ''
-          Like value but not evaluated by Bash. This allows to inject other
+          Like value but evaluated by Bash. This allows to inject other
           variable names or even commands using the `$()` notation.
         '';
         example = "$OTHER_VAR";
@@ -70,8 +92,8 @@
         description = ''
           Prepend to PATH-like environment variables.
 
-          For example name = "PATH"; prefix = "bin"; will expand the path of
-          ./bin and prepend it to the PATH, separated by ':'.
+          For example `name = "PATH"; prefix = "bin";` will expand the path of
+          `./bin` and prepend it to the `PATH`, separated by `:`.
         '';
         example = "bin";
       };
@@ -79,7 +101,9 @@
       unset = mkOption {
         type = types.bool;
         default = false;
-        description = ''Unset the env variable'';
+        description = ''
+          Unset the env variable.
+        '';
       };
     };
   });
@@ -87,7 +111,9 @@ in {
   options.env = mkOption {
     type = types.attrsOf envType;
     default = {};
-    description = '''';
+    description = ''
+      Manage environment variables.
+    '';
   };
 
   config = {
@@ -95,5 +121,6 @@ in {
       "XDG_DATA_DIRS".eval = "$DEVSHELL_DIR/share:\${XDG_DATA_DIRS-}";
     };
     enterShellCommands."env".text = concatStringsSep "\n" (map envToBash (builtins.attrValues config.env));
+    # TODO: collect all env vars, then add them to the menu if they have a description and "visibile == true"
   };
 }

lib/modules/main.nix

@@ -80,18 +80,36 @@ in {
     name = mkOption {
       type = types.str;
       default = "devshell";
+      description = ''
+        Name of the shell.
+      '';
     };
     packages = mkOption {
       type = types.listOf types.package;
       default = [];
+      description = ''
+        Packages to install into the devshell.
+      '';
     };
     enterShellCommands = mkOption {
       type = types.attrsOf entryType;
       default = {};
+      description = ''
+        Commands to run when entering the shell.
+      '';
+      example = {
+        "hello".text = "echo Hello world";
+      };
     };
     interactiveShellCommands = mkOption {
       type = types.attrsOf entryType;
       default = {};
+      description = ''
+        Commands to run when entering an interactive shell.
+      '';
+      example = {
+        "hello".text = "echo Hello world";
+      };
     };
   };