Use mdbook for site, improve docs and readme

README.md

@@ -3,7 +3,12 @@
 
 _Core of a distributed framework for writing Nix Flakes._
 
-`flake-parts` provides the options that represent standard flake attributes and establishes a way of working with `system`. Opinionated features are provided by an ecosystem of modules that you can import.
+`flake-parts` provides the options that represent standard flake attributes 
+and establishes a way of working with `system`.
+Opinionated features are provided by an ecosystem of modules that you can import.
+
+`flake-parts` _itself_ has the goal to be a minimal mirror of the Nix flake schema.
+Used by itself, it is very lightweight. 
 
 # Why Modules?
 
@@ -16,8 +21,20 @@ module system has done for NixOS configurations.
 Unlike NixOS, but following Flakes' spirit, `flake-parts` is not a
 monorepo with the implied goal of absorbing all of open source, but rather
 a single module that other repositories can build upon, while ensuring a
-baseline level of compatibility: which core attribute make up a flake and
-how these are represented as module options.
+baseline level of compatibility: the core attributes that constitute a flake.
+
+# Features
+
+ - Split your `flake.nix` into focused units, each in their own file.
+
+ - Take care of [system](./system.md).
+
+ - Allow users of your library flake to easily integrate your generated flake outputs
+   into their flake.
+
+ - Reuse project logic written by others
+
+<!-- end_of_intro -->
 
 # Getting Started
 

dev/flake-module.nix

@@ -16,6 +16,7 @@
         pkgs.hci
         pkgs.netlify-cli
         pkgs.pandoc
+        pkgs.mdbook
       ];
       shellHook = ''
         ${config.pre-commit.installationScript}

dev/flake.nix

@@ -12,6 +12,8 @@
     pre-commit-hooks-nix.inputs.nixpkgs.follows = "nixpkgs";
 
     hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";
+
+    haskell-flake.url = "github:srid/haskell-flake";
   };
 
   outputs = { self, ... }:

site/.gitignore

@@ -0,0 +1 @@
+book

site/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Robert Hensing", "Various module authors"]
+language = "en"
+multilingual = false
+src = "src"
+title = "flake-parts"

site/flake-module.nix

@@ -8,6 +8,7 @@
         imports = [
           inputs.pre-commit-hooks-nix.flakeModule
           inputs.hercules-ci-effects.flakeModule
+          inputs.haskell-flake.flakeModule
         ];
       };
       opts = eval.options;
@@ -31,9 +32,9 @@
         then opt // { visible = false; }
         else opt // { inherit declarations; };
 
-      optionsDoc = { sourceName, baseUrl, sourcePath, title }: pkgs.runCommand "${sourceName}-doc"
+      optionsDoc = { sourceName, baseUrl, sourcePath, title }: pkgs.runCommand "option-doc-${sourceName}"
         {
-          nativeBuildInputs = [ pkgs.libxslt.bin ];
+          nativeBuildInputs = [ pkgs.libxslt.bin pkgs.pandoc ];
           inputDoc = (pkgs.nixosOptionsDoc {
             options = opts;
             documentType = "none";
@@ -46,75 +47,84 @@
           inherit title;
         } ''
         xsltproc --stringparam title "$title" \
-          -o $out ${./options.xsl} \
+          -o options.db.xml ${./options.xsl} \
           "$inputDoc"
+        mkdir $out
+        pandoc --verbose --from docbook --to html options.db.xml >$out/options.md;
       '';
+
+      repos = {
+        flake-parts = {
+          title = "Core Options";
+          sourceName = "flake-parts";
+          baseUrl = "https://github.com/hercules-ci/flake-parts/blob/main";
+          sourcePath = ../.;
+        };
+        pre-commit-hooks-nix = {
+          title = "pre-commit-hooks.nix";
+          sourceName = "pre-commit-hooks.nix";
+          baseUrl = "https://github.com/hercules-ci/pre-commit-hooks.nix/blob/flakeModule";
+          sourcePath = inputs.pre-commit-hooks-nix;
+        };
+        hercules-ci-effects = {
+          title = "hercules-ci-effects";
+          sourceName = "hercules-ci-effects";
+          baseUrl = "https://github.com/hercules-ci/hercules-ci-effects/blob/master";
+          sourcePath = inputs.hercules-ci-effects;
+        };
+        haskell-flake = {
+          title = "haskell-flake";
+          sourceName = "haskell-flake";
+          baseUrl = "https://github.com/srid/haskell-flake/blob/master";
+          sourcePath = inputs.haskell-flake;
+        };
+      };
+
+      generatedDocs = lib.mapAttrs (k: optionsDoc) repos;
+      generatedDocs' = lib.mapAttrs' (name: value: { name = "generated-docs-${name}"; inherit value; }) generatedDocs;
+
     in
     {
-
       packages = {
-
         siteContent = pkgs.stdenvNoCC.mkDerivation {
           name = "site";
-          nativeBuildInputs = [ pkgs.pandoc pkgs.libxslt.bin ];
-          src = lib.cleanSourceWith {
-            filter = path: type:
-              path == ./.
-              || baseNameOf path == "index.html";
-            src = ./.;
-          };
-          coreOptions = optionsDoc {
-            title = "Core Options";
-            sourceName = "flake-parts";
-            baseUrl = "https://github.com/hercules-ci/flake-parts/blob/main";
-            sourcePath = ../.;
-          };
-          # TODO make this a dynamic input
-          pre_commit_hooks_nixOptions = optionsDoc {
-            title = "pre-commit-hooks.nix";
-            sourceName = "pre-commit-hooks.nix";
-            baseUrl = "https://github.com/hercules-ci/pre-commit-hooks.nix/blob/flakeModule";
-            sourcePath = inputs.pre-commit-hooks-nix;
-          };
-          # TODO make this a dynamic input
-          hercules_ci_effectsOptions = optionsDoc {
-            title = "hercules-ci-effects";
-            sourceName = "hercules-ci-effects";
-            baseUrl = "https://github.com/hercules-ci/hercules-ci-effects/blob/master";
-            sourcePath = inputs.hercules-ci-effects;
-          };
-          # pandoc
-          htmlBefore = ''
-            <html>
-            <head>
-            <title>Options</title>
-            <style type="text/css">
-              a:target { background-color: rgba(239,255,0,0.5); }
-              body {
-                max-width: 40em;
-                margin-left: auto;
-                margin-right: auto;
-              }
-            </style>
-            </head>
-            <body>
-          '';
-          htmlAfter = ''
-            </body>
-            </html>
-          '';
+          nativeBuildInputs = [ pkgs.mdbook ];
+          src = ./.;
           buildPhase = ''
-            ( echo "$htmlBefore";
-              pandoc --verbose --from docbook --to html5 $coreOptions;
-              pandoc --verbose --from docbook --to html5 $hercules_ci_effectsOptions;
-              pandoc --verbose --from docbook --to html5 $pre_commit_hooks_nixOptions;
-              echo "$htmlAfter"; ) >options.html
-          '';
-          installPhase = ''
-            mkdir -p $out
-            cp *.html $out/
+            runHook preBuild
+
+            {
+              while read ln; do
+                case "$ln" in
+                  *end_of_intro*)
+                    break
+                    ;;
+                  *)
+                    echo "$ln"
+                    ;;
+                esac
+              done
+              cat src/intro-continued.md
+            } <${../README.md} >src/README.md
+
+            mkdir -p src/options
+            ${lib.concatStringsSep "\n"
+              (lib.mapAttrsToList
+                (name: generated: ''
+                  cp '${generated}/options.md' 'src/options/${name}.md'
+                '')
+                generatedDocs)
+            }
+
+            mdbook build --dest-dir $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>' \
+              >$out/options.html
+
+            runHook postBuild
           '';
+          dontInstall = true;
         };
-      };
+      } // generatedDocs';
     };
 }

site/options.xsl

@@ -14,6 +14,10 @@
       <title>
         <xsl:value-of select="$title"/>
       </title>
+      <para>Overview:</para>
+      <xsl:for-each select="db:varlistentry">
+        <para><link xlink:href="#{db:term/@xml:id}"><xsl:copy-of select="db:term/db:option"/></link></para>
+      </xsl:for-each>
       <xsl:apply-templates />
     </chapter>
   </xsl:template>

site/src/SUMMARY.md

@@ -0,0 +1,12 @@
+# Summary
+
+- [Introduction](./README.md)
+- [Getting Started](./getting-started.md)
+- [Working with `system`](./system.md)
+- [Reference Documentation](./module-arguments.md)
+  - [Module Arguments](./module-arguments.md)
+  - [Options](./options/flake-parts.md)
+    - [Core `flake-parts`](./options/flake-parts.md)
+    - [`haskell-flake`](./options/haskell-flake.md)
+    - [`hercules-ci-effects`](./options/hercules-ci-effects.md)
+    - [`pre-commit-hooks.nix`](./options/pre-commit-hooks-nix.md)

site/src/getting-started.md

@@ -0,0 +1,38 @@
+
+# Getting Started
+
+## New flake
+
+If your project does not have a flake yet:
+
+```console
+nix flake init -t github:hercules-ci/flake-parts
+```
+
+## Existing flake
+
+Otherwise, add the input,
+
+```
+    flake-parts.url = "github:hercules-ci/flake-parts";
+```
+
+then slide `mkFlake` between your outputs function head and body,
+
+```
+  outputs = { self, flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit self; } {
+      flake = {
+        # Put your original flake attributes here.
+      };
+      systems = [
+        # systems for which you want to build the `perSystem` attributes
+        "x86_64-linux"
+        # ...
+      ];
+      perSystem = { config, ... }: {
+      };
+    };
+```
+
+Now you can start using the flake-parts options.

site/src/intro-continued.md

@@ -0,0 +1,7 @@
+<!-- prefaced by the README intro -->
+
+# This documentation
+
+You can find guides and the options reference in the menu (top left).
+
+A site wide search is available by typing `s`.