docs: better summary + embed modules README.md

modules/dream2nix/mkDerivation/README.md

@@ -0,0 +1 @@
+A package module based on the mkDerivation builder from nixpkgs

modules/flake-parts/render/default.nix

@@ -222,10 +222,10 @@ in {
         installation = mkOption {
           type = types.str;
           description = ''
-            Installation paragraph between installation and options.
+            Paragraph between import and options.
           '';
           default = ''
-            ## Installation
+            ## Import
 
             To import this module into your dream2nix package:
 
@@ -354,7 +354,6 @@ in {
           # - [Reference Documentation]()
           #   - [core (built in)](./options/core.md)
           generated-summary-md = pkgs.writeText "SUMMARY.md" ''
-            - [Reference Documentation]()
             ${
               lib.concatStringsSep "\n"
               (lib.mapAttrsToList

modules/flake-parts/site/default.nix

@@ -53,7 +53,24 @@
 
           rm ./src/intro.md
           cp ${self + /README.md} ./src/intro.md
-          cat ${self'.packages.generated-summary-md} >> ./src/SUMMARY.md
+
+          cp ./src/SUMMARY.md SUMMARY.md.orig
+
+          # insert the generated part of the summary into the origin SUMMARY.md
+          {
+            while read ln; do
+              case "$ln" in
+                "# Modules Reference")
+                  echo "# Modules Reference"
+                  cat ${self'.packages.generated-summary-md}
+                  ;;
+                *)
+                  echo "$ln"
+                  ;;
+              esac
+            done
+          } < SUMMARY.md.orig > src/SUMMARY.md
+
           mkdir -p ./theme
           cp ${self + /modules/dream2nix/core/docs/theme/favicon.png} ./theme/favicon.png
 

modules/flake-parts/site/src/SUMMARY.md

@@ -6,6 +6,8 @@
 # Concepts
 - [dream2nix modules](./modules.md)
 
+# Modules Reference
+
 # Development Roundups
 - [April - June 2022](./development-roundups/2022-april-june.md)
 - [July - September 2022](./development-roundups/2022-july-september.md)

modules/flake-parts/website.nix

@@ -41,7 +41,10 @@
           "dream2nix"
           (lib.strings.escapeNixIdentifier name)
         ];
-        intro = "intro";
+        intro =
+          if lib.pathExists (self + /modules/dream2nix/${name}/README.md)
+          then lib.readFile (self + /modules/dream2nix/${name}/README.md)
+          else "";
         baseUrl = "https://github.com/nix-community/dream2nix/blob/master";
         separateEval = true;
       });