site/make mechanism for eval substitution

flake.nix

@@ -30,19 +30,18 @@
         mkPoetryEnv
         ;
 
-      lessonsLib = import ./lib/lessons.nix {inherit self pkgs lib;};
+      lessonsLib = import ./lib/lessons.nix {inherit pkgs lib;};
 
       site-env = mkPoetryEnv {
         projectDir = self + /site;
         python = pkgs.python311;
       };
 
-      lessonsDocumentation =
-        lessonsLib.generateLessonsDocumentation
-        {
-          lessonsPath = ./lessons;
-          lessonFile = "lesson.md";
-        };
+      lessonsInfo = {
+        lessonsPath = ./lessons;
+        lessonFile = "lesson.md";
+      };
+      lessonsDocumentation = lessonsLib.generateLessonsDocumentation lessonsInfo;
 
       site = pkgs.stdenvNoCC.mkDerivation {
         name = "modules-lessons-site";

lessons/001-a-module/eval.nix

@@ -1,6 +1,4 @@
-let
-  pkgs = import <nixpkgs> {};
-
+{pkgs}: let
   mymodule = {
     imports = [
     ];

lessons/010-basic-types/eval.nix

@@ -1,13 +1,10 @@
-let
-  pkgs = import <nixpkgs> {};
-  inherit (pkgs) lib;
-in
-  (
-    pkgs.lib.evalModules {
-      modules = [
-        ./options.nix
-        ./config.nix
-      ];
-    }
-  )
-  .config
+{pkgs}:
+(
+  pkgs.lib.evalModules {
+    modules = [
+      ./options.nix
+      ./config.nix
+    ];
+  }
+)
+.config

lessons/010-basic-types/lesson.md

@@ -26,6 +26,6 @@ In the `run.sh` file, we evaluate the `eval.nix` file and have it print out a ni
 
 If you execute the run file (`./run.sh`), you should see an output that matches what we have configured.
 
-[//]: # (evaluatedLesson)
+[//]: # (self.eval)
 
 [nixos-manual-basic-types]: https://nixos.org/manual/nixos/stable/#sec-option-types

lessons/010-basic-types/run.sh

@@ -1 +1 @@
-nix eval -f eval.nix --json | nix run nixpkgs#jq -- .
+nix eval -f eval.nix --apply 'x: x {pkgs = import <nixpkgs> {};}' --json | nix run nixpkgs#jq -- .

lib/lessons.nix

@@ -1,5 +1,4 @@
 {
-  self,
   pkgs,
   lib,
   ...
@@ -173,6 +172,29 @@
     ```
   '';
 
+  /*
+  Evalates all files in a lesson directory that start with `eval`.
+
+  Returns an attrset with the key as the file name without the extension and the value as the evaluated value.
+
+  This can be used in the `lesson.md` files with a hidden comment and keyword to substitute the evaluated values.
+  */
+  getLessonsEvals = lessonPath: (
+    builtins.listToAttrs
+    (
+      builtins.map
+      (path: {
+        name = "${lib.removeSuffix ".nix" (builtins.baseNameOf path)}";
+        value = lib.generators.toPretty {} (import path {inherit pkgs;});
+      })
+      (
+        builtins.filter
+        (file: lib.hasPrefix "eval" (builtins.baseNameOf file))
+        (lib.filesystem.listFilesRecursive lessonPath)
+      )
+    )
+  );
+
   /*
   Given a lesson, create the metadata necessary to create the markdown documentation.
   */
@@ -181,7 +203,7 @@
     lessonPath = value;
     rawLesson = builtins.readFile (lib.path.append lessonPath lessonFile);
 
-    commentLineMatch = ''(\[//]: # \(.*\..*\))'';
+    commentLineMatch = ''(\[//]: # \(\./.*\))'';
     commentFileMatch = ''\[//]: # \(\./(.*)\)'';
     linesToReplace = multilineMatch commentLineMatch rawLesson;
     filesToSubstitute = (
@@ -207,19 +229,36 @@
       makeFencedCodeBlock
       filesToSubstitute
     );
+
+    evaluations = getLessonsEvals lessonPath;
+    selfLineMatch = ''(\[//]: # \(self.*\))'';
+    selfAttrMatch = ''\[//]: # \(self\.(.*)\)'';
+    selfLinesToReplace = multilineMatch selfLineMatch rawLesson;
+    selfEvaluationToSubstitue =
+      lib.flatten
+      (
+        builtins.map
+        (
+          multilineMatch
+          selfAttrMatch
+        )
+        selfLinesToReplace
+      );
+    selfValueToSubstitute =
+      builtins.map
+      (x: ''
+        ``` nix
+        ${evaluations.${x}}
+        ```
+      '')
+      selfEvaluationToSubstitue;
   in rec {
     outputParentDir = "lessons/" + lessonDir;
     outputFilePath = outputParentDir + "/" + lessonFile;
     subsLesson = (
       builtins.replaceStrings
-      [''[//]: # (evaluatedLesson)'']
-      [
-        ''
-          ```nix
-          ${(lib.generators.toPretty {} evaluatedLesson)}
-          ```
-        ''
-      ]
+      selfLinesToReplace
+      selfValueToSubstitute
       (
         builtins.replaceStrings
         linesToReplace