Merge branch 'master' of github.com:mlabs-haskell/flake-lang.nix into szg251/sync-rust-flake

Author: szg251

docs/build.nix

@@ -1,21 +1,95 @@
-_: {
+{ flake-parts-lib, inputs, ... }: {
   perSystem = { pkgs, config, ... }:
-    {
-      devShells.dev-docs = pkgs.mkShell {
-        name = "docs-env";
-        packages = [ pkgs.mdbook ];
-        shellHook = config.settings.shell.hook;
-      };
 
-      packages.lambda-buffers-book = pkgs.stdenv.mkDerivation {
-        src = ./.;
-        name = "lambda-buffers-book";
-        buildInputs = [ pkgs.mdbook ];
-        buildPhase = ''
-          cp ${config.packages.lambda-buffers-api-docs}/api.md api.md;
-          mdbook build . --dest-dir $out
-        '';
+    # Note(jaredponn): What is going on here to generate the documentation?
+    # Since flake-parts is using the module system and nixos also uses the
+    # module system, we copy how they generate documentation:
+    #  - The nix function which builds the documentation 
+    #    https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-options-doc/default.nix
+    #  - The file where they actually build the documentation
+    #    https://github.com/NixOS/nixpkgs/blob/master/doc/default.nix
+    let
+      # TODO(jaredponn): make this a module option or something so someone
+      # can set this somewhere else...
+      rootSrcUrl = "https://github.com/mlabs-haskell/flake-lang.nix/blob/master";
+      eval =
+        # pkgs.lib.evalModules
+        flake-parts-lib.evalFlakeModule
+          { inherit inputs; }
+          {
+            imports =
+              [
+                ../flake-lang/build.nix
+              ];
+          };
+      optionsDoc = pkgs.nixosOptionsDoc {
+        inherit (eval) options;
+        documentType = "none";
+        revision = "none";
+        # We only want to include the options provided by us (there's a
+        # bunch of extra garbage provided by flake-parts).
+        # So, we set the attribute `.visible` to `false` for all options
+        # which are not defined in `*.lib.*` (where we recall `*.lib.* is
+        # our stuff)
+        transformOptions =
+          opt:
+          if
+          # Either `lib` is the first thing, or it's in some nested attribute
+            builtins.match ''^(.*\.)?lib(\..+)?$'' opt.name != null
+          then opt
+            //
+            {
+              # Need to do some work s.t. we refer to the
+              # actual github repo instead of the nix
+              # store
+              declarations =
+                builtins.map
+                  (decl:
+                    let matches = builtins.match ''${builtins.toString ./..}/(.*)'' decl;
+                    in if matches != null
+                    then
+                      let matched = builtins.elemAt matches 0;
+                      in
+                      {
+                        # TODO(jaredponn):
+                        # What about
+                        # weird URLS?
+                        # shouldn't we
+                        # escape the
+                        # URL in a
+                        # reasonable
+                        # sense?
+                        url = "${rootSrcUrl}/${matched}";
+                        name = matched;
+                      }
+                    else decl
+                  )
+                  opt.declarations;
+            }
+          else opt // { visible = false; };
       };
 
+    in
+    {
+
+      packages = {
+        # Useful for debugging.
+        docs-raw-json = optionsDoc.optionsJSON;
+        docs-raw-common-mark = optionsDoc.optionsCommonMark;
+
+        # Documentation
+        docs = pkgs.runCommand
+          "flake-lang-docs"
+          { nativeBuildInputs = [ pkgs.pandoc ]; }
+          ''
+            pandoc ${pkgs.lib.escapeShellArg config.packages.docs-raw-common-mark} \
+                --metadata title="flake-lang.nix" \
+                --standalone \
+                --output index.html
+
+            mkdir -p "$out"
+            mv index.html "$out"
+          '';
+      };
     };
 }

examples/build.nix

@@ -7,5 +7,7 @@ _:
     [
       ./haskell-flake-project/build.nix
       ./rust-flake-project/build.nix
+      ./typescript-flake-project/build.nix
+      ./typescript-flake-project-with-extra-dependency/build.nix
     ];
 }

flake-lang/build.nix

@@ -20,11 +20,7 @@
       lib = lib.mkOption {
         type = lib.types.lazyAttrsOf (lib.types.lazyAttrsOf (lib.types.functionTo lib.types.attrs));
         default = { };
-        description = ''
-          Nix functions to help create flakes for languages.
-
-          TODO(jaredponn): document this better.
-        '';
+        visible = false;
       };
     };
     perSystem = flake-parts-lib.mkPerSystemOption ({ pkgs, pkgsForCtl, pkgsForHaskellNix, pkgsForRust, ... }: {
@@ -34,10 +30,10 @@
             type = lib.types.functionTo lib.types.attrs;
             default = import ./flake-purescript.nix pkgsForCtl;
             readOnly = true;
-            description = ''
+            description = lib.mdDoc ''
               TODO(jaredponn): write down documentation here
             '';
-            example = ''
+            example = lib.mdDoc ''
               TODO(jaredponn): write down an example here
             '';
           };
@@ -46,10 +42,10 @@
             type = lib.types.functionTo lib.types.attrs;
             default = import ./flake-rust.nix pkgsForRust;
             readOnly = true;
-            description = ''
+            description = lib.mdDoc ''
               TODO(jaredponn): write down documentation here
             '';
-            example = ''
+            example = lib.mdDoc ''
               TODO(jaredponn): write down an example here
             '';
           };
@@ -58,10 +54,10 @@
             type = lib.types.functionTo lib.types.attrs;
             default = import ./flake-haskell.nix pkgsForHaskellNix;
             readOnly = true;
-            description = ''
+            description = lib.mdDoc ''
               TODO(jaredponn): write down documentation here
             '';
-            example = ''
+            example = lib.mdDoc ''
               TODO(jaredponn): write down an example here
             '';
           };
@@ -70,10 +66,10 @@
             type = lib.types.functionTo lib.types.attrs;
             default = import ./flake-haskell-plutus.nix inputs.cardano-haskell-packages pkgsForHaskellNix;
             readOnly = true;
-            description = ''
+            description = lib.mdDoc ''
               TODO(jaredponn): write down documentation here
             '';
-            example = ''
+            example = lib.mdDoc ''
               TODO(jaredponn): write down an example here
             '';
           };
@@ -82,10 +78,10 @@
             type = lib.types.functionTo lib.types.attrs;
             default = import ./flake-typescript.nix pkgs;
             readOnly = true;
-            description = ''
+            description = lib.mdDoc ''
               TODO(jaredponn): write down documentation here
             '';
-            example = ''
+            example = lib.mdDoc ''
               TODO(jaredponn): write down an example here
             '';
           };