From 7cb146701a5d43cd0768bcec37160067f68f9883 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 11:39:11 +0200
Subject: [PATCH 01/67] add mkdocs-based docs site

---
 docs/mkdocs.yml                               |   5 +
 docs/package.nix                              |  17 ++
 docs/pyproject.toml                           |  11 +
 modules/dream2nix/pip/README.md               |   8 +
 .../flake-parts/reference-website/default.nix | 245 +++++++-----------
 5 files changed, 129 insertions(+), 157 deletions(-)
 create mode 100644 docs/mkdocs.yml
 create mode 100644 docs/package.nix
 create mode 100644 docs/pyproject.toml
 create mode 100644 modules/dream2nix/pip/README.md

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
new file mode 100644
index 00000000..9673161d
--- /dev/null
+++ b/docs/mkdocs.yml
@@ -0,0 +1,5 @@
+site_name: Dream2Nix
+docs_dir: "src"
+site_url: "https://nix-community.github.io/dream2nix"
+site_dir: !ENV out
+
diff --git a/docs/package.nix b/docs/package.nix
new file mode 100644
index 00000000..f31a4ca6
--- /dev/null
+++ b/docs/package.nix
@@ -0,0 +1,17 @@
+{
+  lib,
+  python3,
+}: let
+  package = python3.pkgs.buildPythonPackage {
+    name = "dream2nix_docs";
+    format = "pyproject";
+    src = ./.;
+    nativeBuildInputs = [
+      python3.pkgs.setuptools
+    ];
+    propagatedBuildInputs = with python3.pkgs; [
+      mkdocs
+    ];
+  };
+in
+  package
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
new file mode 100644
index 00000000..e26f1398
--- /dev/null
+++ b/docs/pyproject.toml
@@ -0,0 +1,11 @@
+
+[project]
+name = "dream2nix_docs"
+description = "documentation of dream2nix"
+authors = [{ name = "David Hauer"}, {name = "Paul Haerle", email = "hello@phaer.org"}]
+dynamic = ["version"]
+dependencies = ["mkdocs"]
+
+
+[tool.setuptools]
+packages = [ "dream2nix_docs" ]
diff --git a/modules/dream2nix/pip/README.md b/modules/dream2nix/pip/README.md
new file mode 100644
index 00000000..94db4aed
--- /dev/null
+++ b/modules/dream2nix/pip/README.md
@@ -0,0 +1,8 @@
+---
+state: released
+maintainers: @phaer
+---
+
+# pip
+
+Python packaging via [pip](https://pip.pypa.io/).
diff --git a/modules/flake-parts/reference-website/default.nix b/modules/flake-parts/reference-website/default.nix
index 6e3421d7..af427a18 100644
--- a/modules/flake-parts/reference-website/default.nix
+++ b/modules/flake-parts/reference-website/default.nix
@@ -9,39 +9,33 @@
     system,
     ...
   }: let
-    modules' = self.modules.dream2nix;
-    modules = lib.filterAttrs (name: _: ! lib.elem name excludes) modules';
     dream2nixRoot = ../../../.;
     dream2nix = import dream2nixRoot;
-    excludes = [
-      # NOT WORKING
-      # TODO: fix those
-      "core"
-      "ui"
-      "docs"
-      "assertions"
-      "nixpkgs-overrides"
-
-      # doesn't need to be rendered
-      "_template"
-    ];
-    public = lib.genAttrs [
-      "nodejs-granular-v3"
-      "nodejs-package-lock-v3"
-      "php-composer-lock"
-      "php-granular"
-      "pip"
-      "rust-cargo-lock"
-      "rust-crane"
-    ] (name: null);
-
-    # interface
-    sourcePathStr = toString dream2nix;
     baseUrl = "https://github.com/nix-community/dream2nix/blob/master";
-    specialArgs = {
-      inherit dream2nix;
-      packageSets.nixpkgs = pkgs;
+
+    getOptions = {modules}: let
+      options = lib.flip lib.mapAttrs modules (
+        name: module: let
+          evaluated = lib.evalModules {
+            specialArgs = {
+              inherit dream2nix;
+              packageSets.nixpkgs = pkgs;
+            };
+            modules = [module];
+          };
+        in
+          evaluated.options
+      );
+      docs = lib.flip lib.mapAttrs options (name: options:
+        pkgs.nixosOptionsDoc {
+          inherit options;
+          inherit transformOptions;
+          warningsAreErrors = false;
+        });
+    in {
+      inherit options docs;
     };
+
     transformOptions = opt:
       opt
       // {
@@ -49,7 +43,7 @@
           map
           (
             decl: let
-              subpath = lib.removePrefix sourcePathStr (toString decl);
+              subpath = lib.removePrefix (toString dream2nix) (toString decl);
             in {
               url = baseUrl + subpath;
               name = "dream2nix" + subpath;
@@ -57,144 +51,81 @@
           )
           opt.declarations;
       };
-    # 0 = no chapters, 1 = one level of chapters, 2 = two levels of chapters ...
-    chaptersNesting = 1;
-    # A tree where nodes are (sub)chapters and leafs are options.
-    # Nesting can be arbitrary
-    chaptersTree = {
-      "Modules" =
-        lib.filterAttrs (name: _: public ? ${name}) optionsTree;
-      "Modules (Internal + Experimental)" =
-        lib.filterAttrs (name: _: ! public ? ${name}) optionsTree;
-    };
-    optionsTree = lib.flip lib.mapAttrs modules (
-      name: module: let
-        evaluated = lib.evalModules {
-          inherit specialArgs;
-          modules = [module];
-        };
-      in
-        # lib.trace "Rendering Module ${name}"
-        (builtins.removeAttrs evaluated.options ["_module"])
-    );
 
-    # implementation
-    highlight-js = let
-      highlight-core = pkgs.fetchurl {
-        url = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js";
-        hash = "sha256-g3pvpbDHNrUrveKythkPMF2j/J7UFoHbUyFQcFe1yEY=";
-      };
-      highlight-nix = pkgs.fetchurl {
-        url = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/nix.min.js";
-        hash = "sha256-BLoZ+/OroDAxMsdZ4GFZtQfsg6ZJeLVNeBzN/82dYgk=";
-      };
-    in
-      pkgs.runCommand "highlight-js" {} ''
-        cat ${highlight-core} > $out
-        cat ${highlight-nix} >> $out
+    modules =
+      lib.filterAttrs (
+        name: _:
+          ! lib.elem name
+          [
+            # NOT WORKING
+            # TODO: fix those
+            "core"
+            "ui"
+            "docs"
+            "assertions"
+            "nixpkgs-overrides"
+            # doesn't need to be rendered
+            "_template"
+          ]
+      )
+      dream2nix.modules.dream2nix;
+
+    options = getOptions {
+      inherit modules;
+    };
+
+    referenceDocs = let
+      publicModules =
+        lib.filterAttrs
+        (n: v: lib.pathExists (v + "/README.md"))
+        modules;
+      createReference = name: sourcePath: ''
+        target_dir="$out/${name}/"
+        mkdir -p "$target_dir"
+        ln -s ${sourcePath}/README.md "$target_dir"
+        ln -s ${options.docs.${name}.optionsJSON}/share/doc/nixos/options.json "$target_dir"
       '';
-    highlight-style = pkgs.fetchurl {
-      url = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/vs.min.css";
-      hash = "sha256-E1kfafj5iO+Tw/04hxdSG+OnvczojOXK2K0iCEYfzSw=";
-    };
-    optionsToMdFile = options: let
-      docs = pkgs.nixosOptionsDoc {
-        inherit options;
-        inherit transformOptions;
-        warningsAreErrors = false;
-      };
     in
-      docs.optionsCommonMark;
-
-    mdFiles = nesting: chapters:
-      if nesting == 0
-      then lib.mapAttrs (name: optionsToMdFile) chapters
-      else lib.concatMapAttrs (name: mdFiles (nesting - 1)) chapters;
-
-    mdFilesDir = pkgs.runCommand "md-files-dir" {} ''
-      mkdir -p $out
-      cp -r ${lib.concatStringsSep "\n cp -r " (lib.mapAttrsToList (name: file: "${file} $out/${name}.md") (mdFiles chaptersNesting chaptersTree))}
-    '';
-
-    spacing = depth:
-      if depth == 0
-      then "- "
-      else "  " + spacing (depth - 1);
-
-    # returns "" for chapters with nesting or an md file for chapters with options
-    chapterUrl = nesting: name:
-      if nesting == 0
-      then "options/${name}.md"
-      else "";
-
-    renderChapters = depth: nesting: chapters:
-      lib.concatStringsSep "\n"
-      (lib.flip lib.mapAttrsToList chapters (
-        name: chapter:
-          "${spacing depth}[${name}](${chapterUrl nesting name})"
-          + lib.optionalString (nesting > 0) (renderChapters (depth + 1) (nesting - 1) chapter)
-      ));
-
-    summaryMdFile =
-      pkgs.writeText "summary.md"
-      (renderChapters 0 chaptersNesting chaptersTree);
-
-    mdBookSource = pkgs.runCommand "website-src" {} ''
-      mkdir -p $out/options
-      cp ${summaryMdFile} $out/SUMMARY.md
-      cp -r ${mdFilesDir}/* $out/options/
-
-      # add table of contents for each md file
-      for file in $out/options/*.md; do
-        name="$(basename "$file")"
-        name="''${name%.md}"
-        echo "# $name - options" > "$file.tmp"
-        echo '<!-- toc -->' | cat - "$file" >> "$file.tmp"
-        mv $file.tmp $file
-      done
-    '';
+      pkgs.runCommand "reference" {
+      } ''
+        ${lib.concatStringsSep "\n" (lib.attrValues (lib.mapAttrs createReference publicModules))}
+      '';
 
     website =
       pkgs.runCommand "website" {
         nativeBuildInputs = [
-          pkgs.mdbook
-          pkgs.mdbook-linkcheck
-          # This inserts a table of contents at each '<!-- toc -->'
-          inputs.mdbook-toc.defaultPackage.${system}
+          self.packages.${system}.mkdocs
+          referenceDocs
         ];
       } ''
-        cp -rL --no-preserve=mode ${dream2nixRoot}/website/* ./
-        cp -r ${mdBookSource}/* src/
-
-        # insert highlight.js
-        cp ${highlight-js} ./src/highlight.js
-        cp ${highlight-style} ./src/highlight.css
-
-        # merge original and generated SUMMARY.md
-        cp ${dream2nixRoot}/website/src/SUMMARY.md SUMMARY.md.orig
-        {
-          while read ln; do
-            case "$ln" in
-              "# Modules Reference")
-                echo "# Modules Reference"
-                cat ${mdBookSource}/SUMMARY.md
-                ;;
-              *)
-                echo "$ln"
-                ;;
-            esac
-          done
-        } < SUMMARY.md.orig > src/SUMMARY.md
-
-        # insert icon
-        mkdir -p ./theme
-        cp ${../../../modules/dream2nix/core/docs/theme/favicon.png} ./theme/favicon.png
-
-        ${pkgs.mdbook}/bin/mdbook build --dest-dir out
-        mv out/html $out
+        cp -rL --no-preserve=mode  ${dream2nixRoot}/docs/* .
+        ln -s ${referenceDocs} ./src/reference
+        mkdocs build
       '';
   in {
+    packages.reference = referenceDocs;
     packages.website = website;
-    packages.docs-generated-mdbook-src = mdBookSource;
+    devShells.mkdocs = let
+      package = self.packages.${system}.mkdocs;
+      pythonWithDeps = pkgs.python3.withPackages (
+      ps: [
+          package
+          ps.ipython
+          ps.black
+          ps.pytest
+          ps.pytest-cov
+        ]
+      );
+    in
+      pkgs.mkShell {
+        packages = [
+          pythonWithDeps
+        ];
+      };
+
+    packages.mkdocs = import ../../../docs/package.nix {
+      inherit lib;
+      inherit (pkgs) python3;
+    };
   };
 }

From 92d2d31a4c83622210cf696ebe7ce30d53b26b56 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 13:38:36 +0200
Subject: [PATCH 02/67] add mkdocs-material...

and more configuration. Also fix favicon path
---
 docs/mkdocs.yml  | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/package.nix |  1 +
 2 files changed, 62 insertions(+)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 9673161d..08a4bdf2 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -3,3 +3,64 @@ docs_dir: "src"
 site_url: "https://nix-community.github.io/dream2nix"
 site_dir: !ENV out
 
+plugins:
+  - generate_options
+  - search
+
+nav:
+  - "Introduction": intro.md
+  - "Getting Started": gettingstarted.md
+  - Examples: examples.md
+  - Modules: modules.md
+  - "Overriding Dependencies": overrides.md
+  - "Contact": contact.md
+
+
+markdown_extensions:
+  - tables
+  - admonition
+  - pymdownx.escapeall
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.tasklist
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn
+
+theme:
+  name: material
+  favicon: favicon.png
+  logo: favicon.png
+  font:
+    text: Roboto
+    code: Roboto Mono
+  features:
+    - search.suggest
+    - search.highlight
+    - instant
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.tracking
+    - navigation.sections
+    - navigation.path
+    - navigation.prune
+    - navigation.top
+    - toc.follow
+    - toc.integrate
+    - content.code.annotate
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/nix-community/dream2nix
+      name: Dream2nix on Github
+    - icon: fontawesome/solid/comments
+      link: https://matrix.to/#/#dream2nix:nixos.org
+      name: Dream2nix Matrix Channel
diff --git a/docs/package.nix b/docs/package.nix
index f31a4ca6..c8641779 100644
--- a/docs/package.nix
+++ b/docs/package.nix
@@ -11,6 +11,7 @@
     ];
     propagatedBuildInputs = with python3.pkgs; [
       mkdocs
+      mkdocs-material
     ];
   };
 in

From 318997a795e940d625ed9ac0941ebf662ab8bc40 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 12:27:16 +0200
Subject: [PATCH 03/67] remove mdbook site, move content to docs/

---
 {website => docs}/src/SUMMARY.md              |  0
 {website => docs}/src/contact.md              |  0
 .../development-roundups/2022-april-june.md   |  0
 .../2022-july-september.md                    |  0
 {website => docs}/src/examples.md             |  0
 {website => docs}/src/funding.md              |  0
 {website => docs}/src/gettingstarted.md       |  0
 {website => docs}/src/intro.md                |  0
 {website => docs}/src/modules.md              |  0
 {website => docs}/src/overrides.md            |  0
 .../src/v1-api/consuming/inspect-options.md   |  0
 .../src/v1-api/consuming/override.md          |  0
 .../integrating/integrate-lang2nix-impure.md  |  0
 .../integrating/integrate-lang2nix-pure.md    |  0
 .../src/v1-api/packaging/monorepo.md          |  0
 .../v1-api/packaging/nodejs-init-project.md   |  0
 .../v1-api/packaging/nodejs-multiple-repos.md |  0
 .../src/v1-api/packaging/nodejs-workspaces.md |  0
 {website => docs}/src/v1-api/problems.md      |  0
 {website => docs}/src/v1-api/summary.md       |  0
 {website => docs}/src/v1-api/users.md         |  0
 {website => docs}/src/warning.md              |  0
 website/README.md                             | 10 ------
 website/book.toml                             | 23 --------------
 website/no-edit-options.js                    |  7 -----
 website/style.css                             | 31 -------------------
 26 files changed, 71 deletions(-)
 rename {website => docs}/src/SUMMARY.md (100%)
 rename {website => docs}/src/contact.md (100%)
 rename {website => docs}/src/development-roundups/2022-april-june.md (100%)
 rename {website => docs}/src/development-roundups/2022-july-september.md (100%)
 rename {website => docs}/src/examples.md (100%)
 rename {website => docs}/src/funding.md (100%)
 rename {website => docs}/src/gettingstarted.md (100%)
 rename {website => docs}/src/intro.md (100%)
 rename {website => docs}/src/modules.md (100%)
 rename {website => docs}/src/overrides.md (100%)
 rename {website => docs}/src/v1-api/consuming/inspect-options.md (100%)
 rename {website => docs}/src/v1-api/consuming/override.md (100%)
 rename {website => docs}/src/v1-api/integrating/integrate-lang2nix-impure.md (100%)
 rename {website => docs}/src/v1-api/integrating/integrate-lang2nix-pure.md (100%)
 rename {website => docs}/src/v1-api/packaging/monorepo.md (100%)
 rename {website => docs}/src/v1-api/packaging/nodejs-init-project.md (100%)
 rename {website => docs}/src/v1-api/packaging/nodejs-multiple-repos.md (100%)
 rename {website => docs}/src/v1-api/packaging/nodejs-workspaces.md (100%)
 rename {website => docs}/src/v1-api/problems.md (100%)
 rename {website => docs}/src/v1-api/summary.md (100%)
 rename {website => docs}/src/v1-api/users.md (100%)
 rename {website => docs}/src/warning.md (100%)
 delete mode 100644 website/README.md
 delete mode 100644 website/book.toml
 delete mode 100644 website/no-edit-options.js
 delete mode 100644 website/style.css

diff --git a/website/src/SUMMARY.md b/docs/src/SUMMARY.md
similarity index 100%
rename from website/src/SUMMARY.md
rename to docs/src/SUMMARY.md
diff --git a/website/src/contact.md b/docs/src/contact.md
similarity index 100%
rename from website/src/contact.md
rename to docs/src/contact.md
diff --git a/website/src/development-roundups/2022-april-june.md b/docs/src/development-roundups/2022-april-june.md
similarity index 100%
rename from website/src/development-roundups/2022-april-june.md
rename to docs/src/development-roundups/2022-april-june.md
diff --git a/website/src/development-roundups/2022-july-september.md b/docs/src/development-roundups/2022-july-september.md
similarity index 100%
rename from website/src/development-roundups/2022-july-september.md
rename to docs/src/development-roundups/2022-july-september.md
diff --git a/website/src/examples.md b/docs/src/examples.md
similarity index 100%
rename from website/src/examples.md
rename to docs/src/examples.md
diff --git a/website/src/funding.md b/docs/src/funding.md
similarity index 100%
rename from website/src/funding.md
rename to docs/src/funding.md
diff --git a/website/src/gettingstarted.md b/docs/src/gettingstarted.md
similarity index 100%
rename from website/src/gettingstarted.md
rename to docs/src/gettingstarted.md
diff --git a/website/src/intro.md b/docs/src/intro.md
similarity index 100%
rename from website/src/intro.md
rename to docs/src/intro.md
diff --git a/website/src/modules.md b/docs/src/modules.md
similarity index 100%
rename from website/src/modules.md
rename to docs/src/modules.md
diff --git a/website/src/overrides.md b/docs/src/overrides.md
similarity index 100%
rename from website/src/overrides.md
rename to docs/src/overrides.md
diff --git a/website/src/v1-api/consuming/inspect-options.md b/docs/src/v1-api/consuming/inspect-options.md
similarity index 100%
rename from website/src/v1-api/consuming/inspect-options.md
rename to docs/src/v1-api/consuming/inspect-options.md
diff --git a/website/src/v1-api/consuming/override.md b/docs/src/v1-api/consuming/override.md
similarity index 100%
rename from website/src/v1-api/consuming/override.md
rename to docs/src/v1-api/consuming/override.md
diff --git a/website/src/v1-api/integrating/integrate-lang2nix-impure.md b/docs/src/v1-api/integrating/integrate-lang2nix-impure.md
similarity index 100%
rename from website/src/v1-api/integrating/integrate-lang2nix-impure.md
rename to docs/src/v1-api/integrating/integrate-lang2nix-impure.md
diff --git a/website/src/v1-api/integrating/integrate-lang2nix-pure.md b/docs/src/v1-api/integrating/integrate-lang2nix-pure.md
similarity index 100%
rename from website/src/v1-api/integrating/integrate-lang2nix-pure.md
rename to docs/src/v1-api/integrating/integrate-lang2nix-pure.md
diff --git a/website/src/v1-api/packaging/monorepo.md b/docs/src/v1-api/packaging/monorepo.md
similarity index 100%
rename from website/src/v1-api/packaging/monorepo.md
rename to docs/src/v1-api/packaging/monorepo.md
diff --git a/website/src/v1-api/packaging/nodejs-init-project.md b/docs/src/v1-api/packaging/nodejs-init-project.md
similarity index 100%
rename from website/src/v1-api/packaging/nodejs-init-project.md
rename to docs/src/v1-api/packaging/nodejs-init-project.md
diff --git a/website/src/v1-api/packaging/nodejs-multiple-repos.md b/docs/src/v1-api/packaging/nodejs-multiple-repos.md
similarity index 100%
rename from website/src/v1-api/packaging/nodejs-multiple-repos.md
rename to docs/src/v1-api/packaging/nodejs-multiple-repos.md
diff --git a/website/src/v1-api/packaging/nodejs-workspaces.md b/docs/src/v1-api/packaging/nodejs-workspaces.md
similarity index 100%
rename from website/src/v1-api/packaging/nodejs-workspaces.md
rename to docs/src/v1-api/packaging/nodejs-workspaces.md
diff --git a/website/src/v1-api/problems.md b/docs/src/v1-api/problems.md
similarity index 100%
rename from website/src/v1-api/problems.md
rename to docs/src/v1-api/problems.md
diff --git a/website/src/v1-api/summary.md b/docs/src/v1-api/summary.md
similarity index 100%
rename from website/src/v1-api/summary.md
rename to docs/src/v1-api/summary.md
diff --git a/website/src/v1-api/users.md b/docs/src/v1-api/users.md
similarity index 100%
rename from website/src/v1-api/users.md
rename to docs/src/v1-api/users.md
diff --git a/website/src/warning.md b/docs/src/warning.md
similarity index 100%
rename from website/src/warning.md
rename to docs/src/warning.md
diff --git a/website/README.md b/website/README.md
deleted file mode 100644
index 9cf713c2..00000000
--- a/website/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Website
-
-This directory contains markdown pages under ./src which are rendered to an html website using the tool mdbook.
-
-The website can be built via:
-```shellSession
-$ nix build .#website
-```
-
-In addition to what's already in ./src, this derivation generates and inserts reference documentation pages. One for each dream2nix module in /modules/dream2nix.
diff --git a/website/book.toml b/website/book.toml
deleted file mode 100644
index 225aae0b..00000000
--- a/website/book.toml
+++ /dev/null
@@ -1,23 +0,0 @@
-[book]
-authors = ["David Hauer", "Various contributors"]
-language = "en"
-multilingual = false
-src = "src"
-title = "dream2nix"
-
-[output.html]
-git-repository-url = "https://github.com/nix-community/dream2nix"
-edit-url-template = "https://github.com/nix-community/dream2nix/edit/main/modules/dream2nix/{path}"
-no-section-label = true
-additional-css = [ "style.css" ]
-additional-js = [ "no-edit-options.js" ]
-
-[output.html.print]
-enable = false  # big single page; don't need that
-
-[output.linkcheck]
-follow-web-links = false # no Internet during the build
-
-[preprocessor.toc]
-command = "mdbook-toc"
-renderer = ["html"]
diff --git a/website/no-edit-options.js b/website/no-edit-options.js
deleted file mode 100644
index e63e56ad..00000000
--- a/website/no-edit-options.js
+++ /dev/null
@@ -1,7 +0,0 @@
-
-if (window.location.pathname.match(/options/)) {
-  var buttons = document.querySelector("#menu-bar > div.right-buttons")
-  if (buttons != null) {
-    buttons.style.display = "none"
-  }
-}
diff --git a/website/style.css b/website/style.css
deleted file mode 100644
index d3857ff0..00000000
--- a/website/style.css
+++ /dev/null
@@ -1,31 +0,0 @@
-h1.menu-title::before {
-  content: "";
-  display: inline-block;
-  background-image: url(./favicon.png);
-  background-repeat: no-repeat;
-  background-size: contain;
-  width: 1.8ex;
-  height: 1.8ex;
-  margin-right: 0.9ex;
-  vertical-align: middle;
-}
-.light {
-  --links: #058;
-  --sidebar-active: #0af;
-}
-.sidebar .sidebar-scrollbox {
-  /* We don't use numbers, so we can take a consistent amount of space */
-  padding: var(--page-padding) !important;
-}
-.hljs {
-  background-color: #f6f7f6;
-}
-@media (prefers-color-scheme: dark) {
-  .hljs {
-    background-color: #1d1f21;
-  }
-}
-/* prevents chapters without links to be grey */
-.chapter li {
-  color: #000;
-}

From 7f355a950680c780f0f132f196a015006fef5c10 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 13:58:43 +0200
Subject: [PATCH 04/67] move notes/module-system-problems to src

---
 .../2022-april-problems-of-nixos-module-system.md}                | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/{notes/module-system-problems.md => src/development-roundups/2022-april-problems-of-nixos-module-system.md} (100%)

diff --git a/docs/notes/module-system-problems.md b/docs/src/development-roundups/2022-april-problems-of-nixos-module-system.md
similarity index 100%
rename from docs/notes/module-system-problems.md
rename to docs/src/development-roundups/2022-april-problems-of-nixos-module-system.md

From 6617d9f90c753c8f94165c852cb26071cfb2c082 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 13:59:25 +0200
Subject: [PATCH 05/67] remove redundant content in docs

---
 docs/mkdocs.yml                 | 14 +++++++++-----
 docs/src/SUMMARY.md             | 17 -----------------
 docs/src/contact.md             |  2 --
 docs/src/examples.md            |  7 -------
 docs/src/funding.md             |  2 --
 docs/src/gettingstarted.md      |  2 --
 docs/src/{intro.md => index.md} |  0
 docs/src/warning.md             |  1 -
 8 files changed, 9 insertions(+), 36 deletions(-)
 delete mode 100644 docs/src/SUMMARY.md
 delete mode 100644 docs/src/contact.md
 delete mode 100644 docs/src/examples.md
 delete mode 100644 docs/src/funding.md
 rename docs/src/{intro.md => index.md} (100%)
 delete mode 100644 docs/src/warning.md

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 08a4bdf2..139c6aaf 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -8,12 +8,15 @@ plugins:
   - search
 
 nav:
-  - "Introduction": intro.md
+  - "Introduction": index.md
   - "Getting Started": gettingstarted.md
-  - Examples: examples.md
-  - Modules: modules.md
-  - "Overriding Dependencies": overrides.md
-  - "Contact": contact.md
+  - Concepts:
+      - Modules: modules.md
+      - "Overriding Dependencies": overrides.md
+  - Examples:
+      - "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
+      - "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
+      - "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
 
 
 markdown_extensions:
@@ -26,6 +29,7 @@ markdown_extensions:
   - pymdownx.snippets
   - pymdownx.superfences
   - pymdownx.tasklist
+  - pymdownx.details
 
 validation:
   omitted_files: warn
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
deleted file mode 100644
index 5167b800..00000000
--- a/docs/src/SUMMARY.md
+++ /dev/null
@@ -1,17 +0,0 @@
-
-- [Introduction](./intro.md)
-- [Getting started](./gettingstarted.md)
-- [Contact](./contact.md)
-
-# Examples
-- [Examples](./examples.md)
-# Concepts
-- [Modules](./modules.md)
-- [Overriding Dependencies](./overrides.md)
-
-# Modules Reference
-
-# Development Roundups
-- [April - June 2022](./development-roundups/2022-april-june.md)
-- [July - September 2022](./development-roundups/2022-july-september.md)
-
diff --git a/docs/src/contact.md b/docs/src/contact.md
deleted file mode 100644
index 6f09d349..00000000
--- a/docs/src/contact.md
+++ /dev/null
@@ -1,2 +0,0 @@
-If you run into any problems or would like to discuss the project,
-check out the [#dream2nix:nixos.org](https://matrix.to/#/#dream2nix:nixos.org) Matrix channel.
diff --git a/docs/src/examples.md b/docs/src/examples.md
deleted file mode 100644
index 04de5cc7..00000000
--- a/docs/src/examples.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Examples for dream2nix
-
-- [👉 example repository](https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages)
-- [👉 example repository using flakes](https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
-- [👉 example packages](https://github.com/nix-community/dream2nix/tree/main/examples/packages)
-  - [👉 basics](https://github.com/nix-community/dream2nix/tree/main/examples/packages/basics)
-  - [👉 languages](https://github.com/nix-community/dream2nix/tree/main/examples/packages/languages)
diff --git a/docs/src/funding.md b/docs/src/funding.md
deleted file mode 100644
index eb89b5ce..00000000
--- a/docs/src/funding.md
+++ /dev/null
@@ -1,2 +0,0 @@
-This project was funded by [NLnet](https://nlnet.nl/), which is a great way to get your open source project funded. **Applications are still open, you can [apply today](https://nlnet.nl/propose)**.
-For more information about dream2nix' funding, please refer to the [funding section of the readme](https://github.com/nix-community/dream2nix#funding)
diff --git a/docs/src/gettingstarted.md b/docs/src/gettingstarted.md
index 2acecd8f..eb4807e0 100644
--- a/docs/src/gettingstarted.md
+++ b/docs/src/gettingstarted.md
@@ -1,5 +1,3 @@
-## Getting started
-
 To package a piece of software with dream2nix, you'd typically start with
 a bare-bones dream2nix flake like this:
 
diff --git a/docs/src/intro.md b/docs/src/index.md
similarity index 100%
rename from docs/src/intro.md
rename to docs/src/index.md
diff --git a/docs/src/warning.md b/docs/src/warning.md
deleted file mode 100644
index 7dec95a9..00000000
--- a/docs/src/warning.md
+++ /dev/null
@@ -1 +0,0 @@
-!!! Warning: dream2nix is unstable software. While simple UX is one of our main focus points, the APIs  are still under development. Do expect changes that will break your setup.

From 229d5a93abab5599927bd308180fa3e9f22a17d0 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 13:59:34 +0200
Subject: [PATCH 06/67] fix admonition (mkdocs syntax)

---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 007e36f8..52cf35f2 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,9 @@
   <a href="https://github.com/nix-community/dream2nix/tree/main/examples/packages">Example Packages</a>
 </p>
 
-!!! Warning: dream2nix is unstable software. While simple UX is one of our main focus points, the APIs  are still under development. Do expect changes that will break your setup.
+!!! warning
+
+    dream2nix is unstable software. While simple UX is one of our main focus points, the APIs  are still under development. Do expect changes that will break your setup.
 
 ### legacy dream2nix
 

From 4e3a5000e01999cb55e47ae8f57e16dbeae57721 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 14:08:49 +0200
Subject: [PATCH 07/67] fix logo style in header

---
 docs/mkdocs.yml    | 4 ++++
 docs/src/style.css | 4 ++++
 2 files changed, 8 insertions(+)
 create mode 100644 docs/src/style.css

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 139c6aaf..d4c99847 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -7,6 +7,10 @@ plugins:
   - generate_options
   - search
 
+extra_css:
+  - style.css
+
+
 nav:
   - "Introduction": index.md
   - "Getting Started": gettingstarted.md
diff --git a/docs/src/style.css b/docs/src/style.css
new file mode 100644
index 00000000..899bf2d7
--- /dev/null
+++ b/docs/src/style.css
@@ -0,0 +1,4 @@
+.md-header .md-logo {
+    background-color: white;
+    border-radius: 100%;
+}

From c644d0b76ae0a46445d05103175a808e3e8df8b9 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 14:09:06 +0200
Subject: [PATCH 08/67] fix link in gettingstarted

---
 docs/src/gettingstarted.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/src/gettingstarted.md b/docs/src/gettingstarted.md
index eb4807e0..dee8c24b 100644
--- a/docs/src/gettingstarted.md
+++ b/docs/src/gettingstarted.md
@@ -58,8 +58,8 @@ And a `default.nix` that looks like this:
 ```
 
 To find out which dream2nix modules to import, browse through the modules
-on the left and the [examples](./examples.md). When getting started, the
-'/packages/languages' collection will be most helpful.
+on the left and the [examples](https://github.com/nix-community/dream2nix/tree/main/examples/packages). When getting started, the
+`./packages/languages` collection will be most helpful.
 
 Once you have imported a module, this module will make ecosystem-dependent
 functions available to create your package definition, such as `mkDerivation`

From ddf9ba346bc0e5c4ec451a6345c136bfc9ea92e0 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 14:40:43 +0200
Subject: [PATCH 09/67] docs/modules: fix header hierachy

---
 docs/src/modules.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/src/modules.md b/docs/src/modules.md
index e054787e..0091af81 100644
--- a/docs/src/modules.md
+++ b/docs/src/modules.md
@@ -6,9 +6,9 @@ For some more background information, check out the initial exploration of this
 
 @edolstra 's [talk about this topic](https://www.youtube.com/watch?v=dTd499Y31ig) is also worth watching.
 
-# Benefits
+## Benefits
 
-## Deprecate override functions
+### Deprecate override functions
 
 Changing options of packages in nixpkgs can require chaining different override functions like this:
 
@@ -39,7 +39,7 @@ Changing options of packages in nixpkgs can require chaining different override
 
 See htop module definition [here](https://github.com/nix-community/dream2nix/blob/main/examples/packages/basics/htop-with-flags/default.nix).
 
-## Type safety
+### Type safety
 
 The following code in nixpkgs mkDerivation mysteriously skips the patches:
 
@@ -56,7 +56,7 @@ mkDerivation {
 A definition for option `[...].dontPatch' is not of type `boolean' [...]
 ```
 
-## Catch typos
+### Catch typos
 
 The following code in nixpkgs mkDerivation builds **without** openssl_3.
 
@@ -73,7 +73,7 @@ mkDerivation {
 The option `[...].nativBuildInputs' does not exist
 ```
 
-## Environment variables clearly defined
+### Environment variables clearly defined
 
 `dream2nix` requires a clear distinction between known parameters and user-defined variables.
 Defining `SOME_VARIABLE` at the top-level, would raise:
@@ -93,7 +93,7 @@ Instead it has to be defined under `env.`:
 }
 ```
 
-## Documentation / Discoverability
+### Documentation / Discoverability
 
 No more digging the source code to find possible options to override.
 
@@ -101,11 +101,11 @@ Documentation similar to [search.nixos.org](https://search.nixos.org) can be gen
 
 Every package built with `dream2nix` has a `.docs` attribute that builds an html documentation describing it's options.
 
-## Package blueprints
+### Package blueprints
 
 With `dream2nix`, packages don't need to be fully declared. Options can be left without defaults, requiring the consumer to complete the definition.
 
-## Flexibility
+### Flexibility
 
 The nixos module system gives maintainers more freedom over how packages are split into modules. Separation of concerns can be implemented more easily.
 For example, the dependency tree of a package set can be factored out into a separate module, allowing for simpler modification.

From 280bebed2c4f47199e7b693206a865e12163ae42 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 14:41:16 +0200
Subject: [PATCH 10/67] docs: don't use navigation pruning

---
 docs/mkdocs.yml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index d4c99847..cb4c296f 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -12,10 +12,10 @@ extra_css:
 
 
 nav:
-  - "Introduction": index.md
+  - "Home": index.md
   - "Getting Started": gettingstarted.md
   - Concepts:
-      - Modules: modules.md
+      - "Modules": modules.md
       - "Overriding Dependencies": overrides.md
   - Examples:
       - "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
@@ -56,9 +56,7 @@ theme:
     - navigation.instant.prefetch
     - navigation.instant.progress
     - navigation.tracking
-    - navigation.sections
     - navigation.path
-    - navigation.prune
     - navigation.top
     - toc.follow
     - toc.integrate

From 42ff2e8d4ddb54c8653efc6a1fb15bfca090758a Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 12:24:00 +0200
Subject: [PATCH 11/67] move dreamDocs out of docs dir

to reduce unecessary rebuilds
---
 docs/mkdocs.yml                                |  1 -
 docs/package.nix                               | 18 ------------------
 docs/pyproject.toml                            | 11 -----------
 .../flake-parts/reference-website/default.nix  | 14 +++++---------
 4 files changed, 5 insertions(+), 39 deletions(-)
 delete mode 100644 docs/package.nix
 delete mode 100644 docs/pyproject.toml

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index cb4c296f..df01ee24 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -4,7 +4,6 @@ site_url: "https://nix-community.github.io/dream2nix"
 site_dir: !ENV out
 
 plugins:
-  - generate_options
   - search
 
 extra_css:
diff --git a/docs/package.nix b/docs/package.nix
deleted file mode 100644
index c8641779..00000000
--- a/docs/package.nix
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  lib,
-  python3,
-}: let
-  package = python3.pkgs.buildPythonPackage {
-    name = "dream2nix_docs";
-    format = "pyproject";
-    src = ./.;
-    nativeBuildInputs = [
-      python3.pkgs.setuptools
-    ];
-    propagatedBuildInputs = with python3.pkgs; [
-      mkdocs
-      mkdocs-material
-    ];
-  };
-in
-  package
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
deleted file mode 100644
index e26f1398..00000000
--- a/docs/pyproject.toml
+++ /dev/null
@@ -1,11 +0,0 @@
-
-[project]
-name = "dream2nix_docs"
-description = "documentation of dream2nix"
-authors = [{ name = "David Hauer"}, {name = "Paul Haerle", email = "hello@phaer.org"}]
-dynamic = ["version"]
-dependencies = ["mkdocs"]
-
-
-[tool.setuptools]
-packages = [ "dream2nix_docs" ]
diff --git a/modules/flake-parts/reference-website/default.nix b/modules/flake-parts/reference-website/default.nix
index af427a18..8ec0823b 100644
--- a/modules/flake-parts/reference-website/default.nix
+++ b/modules/flake-parts/reference-website/default.nix
@@ -94,7 +94,8 @@
     website =
       pkgs.runCommand "website" {
         nativeBuildInputs = [
-          self.packages.${system}.mkdocs
+          pkgs.python3.pkgs.mkdocs
+          pkgs.python3.pkgs.mkdocs-material
           referenceDocs
         ];
       } ''
@@ -106,10 +107,10 @@
     packages.reference = referenceDocs;
     packages.website = website;
     devShells.mkdocs = let
-      package = self.packages.${system}.mkdocs;
       pythonWithDeps = pkgs.python3.withPackages (
-      ps: [
-          package
+        ps: [
+          self.packages.${system}.mkdocs
+          self.packages.${system}.mkdocs-material
           ps.ipython
           ps.black
           ps.pytest
@@ -122,10 +123,5 @@
           pythonWithDeps
         ];
       };
-
-    packages.mkdocs = import ../../../docs/package.nix {
-      inherit lib;
-      inherit (pkgs) python3;
-    };
   };
 }

From bb4b27886f4b2d3b1953e030d546b12e07aa89dc Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 18:56:01 +0200
Subject: [PATCH 12/67] add render_options hook

---
 docs/hooks/render_options.py                  | 106 ++++++++++++++++++
 docs/mkdocs.yml                               |   6 +-
 .../flake-parts/reference-website/default.nix |   2 +-
 3 files changed, 112 insertions(+), 2 deletions(-)
 create mode 100644 docs/hooks/render_options.py

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
new file mode 100644
index 00000000..5f81352a
--- /dev/null
+++ b/docs/hooks/render_options.py
@@ -0,0 +1,106 @@
+import logging
+import json
+from pathlib import Path
+
+from mkdocs.structure.pages import Page
+from mkdocs.structure.files import Files
+from mkdocs.config.defaults import MkDocsConfig
+
+
+log = logging.getLogger("mkdocs")
+
+
+def is_reference_page(page: Page) -> bool:
+    return page.file.src_path.startswith("reference/")
+
+
+def slugify(name: str) -> str:
+    return name.lower().replace(".", "-")
+
+
+def preprocess_options(options):
+    tree = {}
+    for name, option in options.items():
+        if name.startswith("_module"):
+            continue
+        cursor = tree
+        parts = name.split(".")
+        for index, part in enumerate(parts):
+            if part not in cursor:
+                if index + 1 == len(parts):
+                    cursor[part] = option
+                else:
+                    cursor[part] = dict()
+                    cursor = cursor[part]
+            else:
+                cursor = cursor[part]
+
+    return tree
+
+
+def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, files: Files):
+    if not is_reference_page(page):
+        return markdown
+
+    src_path = Path(config.docs_dir) / page.file.src_path
+    options_path = src_path.parent / "options.json"
+    if not options_path.exists():
+        log.error(f"{options_path} does not exist")
+
+    jinja = config.theme.get_env()
+    jinja.filters["slugify"] = slugify
+    options_template = jinja.from_string(
+        """
+## Options
+{%- for name, children in options.items() recursive %}
+
+##{{loop.depth * "#"}} {{ name }}
+
+{% if "type" in children -%}
+
+{{ children.description }}
+
+<table>
+    <tr>
+        <td>type</td>
+        <td><code>{{ children.type }}</code> {{ "(read only)" if children.readOnly else "" }}</td>
+    </tr>
+    <tr>
+        <td>source</td>
+        <td>{%- for d in children.declarations -%}<a href="{{d.url}}">{{d.name}}</a>{{ ", " if not loop.last else "" }}{%- endfor -%}</td>
+    </tr>
+    {%- if children.default -%}
+    <tr>
+        <td>default</td>
+        <td><pre>{{(children.default | default({})).text}}</pre></td>
+    </tr>
+    {%- endif -%}
+    {%- if children.exampl -%}
+    <tr>
+        <td>example</td>
+        <td>
+                <pre>{{(children.example | default({})).text | replace("\n", "\\n")}}</pre>
+    </td>
+    </tr>
+    {%- endif -%}
+</table>
+
+{#
+```json
+{{ children | tojson(indent=2)}}
+```
+#}
+
+{%- else -%}
+{{ loop(children.items()) }}
+{%- endif %}
+{%- endfor %}
+"""
+    )
+
+    with open(options_path, "r") as f:
+        options = json.load(f)
+
+    tree = preprocess_options(options)
+    rendered = options_template.render(options=tree)
+    return markdown + rendered
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index df01ee24..e5f5e942 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -6,6 +6,9 @@ site_dir: !ENV out
 plugins:
   - search
 
+hooks:
+  - hooks/render_options.py
+
 extra_css:
   - style.css
 
@@ -20,7 +23,8 @@ nav:
       - "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
       - "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
       - "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
-
+  - Reference:
+      - "pip": reference/pip/index.md
 
 markdown_extensions:
   - tables
diff --git a/modules/flake-parts/reference-website/default.nix b/modules/flake-parts/reference-website/default.nix
index 8ec0823b..78a0263c 100644
--- a/modules/flake-parts/reference-website/default.nix
+++ b/modules/flake-parts/reference-website/default.nix
@@ -82,7 +82,7 @@
       createReference = name: sourcePath: ''
         target_dir="$out/${name}/"
         mkdir -p "$target_dir"
-        ln -s ${sourcePath}/README.md "$target_dir"
+        ln -s ${sourcePath}/README.md "$target_dir/index.md"
         ln -s ${options.docs.${name}.optionsJSON}/share/doc/nixos/options.json "$target_dir"
       '';
     in

From e01ce3d09b60a9cfd6cb1755bf16eb89b97e5a10 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 22:29:50 +0200
Subject: [PATCH 13/67] add favicon

---
 docs/src/favicon.png | Bin 0 -> 5874 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 docs/src/favicon.png

diff --git a/docs/src/favicon.png b/docs/src/favicon.png
new file mode 100644
index 0000000000000000000000000000000000000000..a4559f303100edd79521a68d81333f7da22e73a5
GIT binary patch
literal 5874
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
IM6N<$f)IsR%m4rY

literal 0
HcmV?d00001


From 44f9f95b362397f0e6385e913905a4ea5de542f6 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 22:30:12 +0200
Subject: [PATCH 14/67] don't integrate toc

---
 docs/mkdocs.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index e5f5e942..d94407ab 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -62,7 +62,6 @@ theme:
     - navigation.path
     - navigation.top
     - toc.follow
-    - toc.integrate
     - content.code.annotate
 
 extra:

From c1e70d4528fff9fe3e6487ce17104ef8048a113b Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 11 Jun 2024 22:30:30 +0200
Subject: [PATCH 15/67] remove unecessary font declaration

---
 docs/mkdocs.yml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index d94407ab..eda0daf1 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -48,9 +48,6 @@ theme:
   name: material
   favicon: favicon.png
   logo: favicon.png
-  font:
-    text: Roboto
-    code: Roboto Mono
   features:
     - search.suggest
     - search.highlight

From 6ff41abd61f0992ea1139f5938a15433e72da755 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Thu, 13 Jun 2024 11:54:11 +0200
Subject: [PATCH 16/67] docs: fix devshell

---
 modules/flake-parts/reference-website/default.nix | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/modules/flake-parts/reference-website/default.nix b/modules/flake-parts/reference-website/default.nix
index 78a0263c..43bdff2e 100644
--- a/modules/flake-parts/reference-website/default.nix
+++ b/modules/flake-parts/reference-website/default.nix
@@ -106,11 +106,9 @@
   in {
     packages.reference = referenceDocs;
     packages.website = website;
-    devShells.mkdocs = let
+    devShells.website = let
       pythonWithDeps = pkgs.python3.withPackages (
         ps: [
-          self.packages.${system}.mkdocs
-          self.packages.${system}.mkdocs-material
           ps.ipython
           ps.black
           ps.pytest
@@ -119,6 +117,7 @@
       );
     in
       pkgs.mkShell {
+        inputsFrom = [self.packages.${system}.website];
         packages = [
           pythonWithDeps
         ];

From 5c6e0e5e9a9f23014e69c2dd08949ba1621fa9f7 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Thu, 13 Jun 2024 13:05:36 +0200
Subject: [PATCH 17/67] docs: add mkdocs-awesome-pages-plugin

---
 docs/mkdocs.yml                               | 15 +----
 docs/src/.pages                               | 14 +++++
 docs/src/v1-api/.pages                        |  3 +
 .../flake-parts/reference-website/default.nix | 21 +++++++
 .../mkdocs-awesome-pages-plugin.nix           | 56 +++++++++++++++++++
 5 files changed, 95 insertions(+), 14 deletions(-)
 create mode 100644 docs/src/.pages
 create mode 100644 docs/src/v1-api/.pages
 create mode 100644 modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index eda0daf1..199044d3 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -5,6 +5,7 @@ site_dir: !ENV out
 
 plugins:
   - search
+  - awesome-pages
 
 hooks:
   - hooks/render_options.py
@@ -12,20 +13,6 @@ hooks:
 extra_css:
   - style.css
 
-
-nav:
-  - "Home": index.md
-  - "Getting Started": gettingstarted.md
-  - Concepts:
-      - "Modules": modules.md
-      - "Overriding Dependencies": overrides.md
-  - Examples:
-      - "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
-      - "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
-      - "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
-  - Reference:
-      - "pip": reference/pip/index.md
-
 markdown_extensions:
   - tables
   - admonition
diff --git a/docs/src/.pages b/docs/src/.pages
new file mode 100644
index 00000000..a6cbad31
--- /dev/null
+++ b/docs/src/.pages
@@ -0,0 +1,14 @@
+nav:
+  - "Home": index.md
+  - "Getting Started": gettingstarted.md
+  - Concepts:
+      - "Modules": modules.md
+      - "Overriding Dependencies": overrides.md
+  - Reference: reference
+  - Examples:
+      - "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
+      - "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
+      - "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
+  - Notes:
+    - "v1 API design docs": v1-api
+    - development-roundups
diff --git a/docs/src/v1-api/.pages b/docs/src/v1-api/.pages
new file mode 100644
index 00000000..eef6efe1
--- /dev/null
+++ b/docs/src/v1-api/.pages
@@ -0,0 +1,3 @@
+nav:
+    - summary.md
+    - ...
diff --git a/modules/flake-parts/reference-website/default.nix b/modules/flake-parts/reference-website/default.nix
index 43bdff2e..9d2e47ae 100644
--- a/modules/flake-parts/reference-website/default.nix
+++ b/modules/flake-parts/reference-website/default.nix
@@ -84,6 +84,11 @@
         mkdir -p "$target_dir"
         ln -s ${sourcePath}/README.md "$target_dir/index.md"
         ln -s ${options.docs.${name}.optionsJSON}/share/doc/nixos/options.json "$target_dir"
+        cat > "$target_dir/.pages" <<EOF
+        collapse_single_pages: true
+        nav:
+          - ...
+        EOF
       '';
     in
       pkgs.runCommand "reference" {
@@ -96,6 +101,7 @@
         nativeBuildInputs = [
           pkgs.python3.pkgs.mkdocs
           pkgs.python3.pkgs.mkdocs-material
+          self.packages.${system}.mkdocs-awesome-pages-plugin
           referenceDocs
         ];
       } ''
@@ -104,6 +110,21 @@
         mkdocs build
       '';
   in {
+    packages.mkdocs-awesome-pages-plugin = pkgs.callPackage ./mkdocs-awesome-pages-plugin.nix {
+      inherit
+        (pkgs.python3.pkgs)
+        buildPythonPackage
+        mkdocs
+        wcmatch
+        natsort
+        beautifulsoup4
+        mock-open
+        importlib-metadata
+        poetry-core
+        pytestCheckHook
+        pythonOlder
+        ;
+    };
     packages.reference = referenceDocs;
     packages.website = website;
     devShells.website = let
diff --git a/modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix b/modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix
new file mode 100644
index 00000000..f7bf1734
--- /dev/null
+++ b/modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix
@@ -0,0 +1,56 @@
+{
+  lib,
+  buildPythonPackage,
+  fetchFromGitHub,
+  poetry-core,
+  mkdocs,
+  wcmatch,
+  natsort,
+  pytestCheckHook,
+  beautifulsoup4,
+  mock-open,
+  importlib-metadata,
+  pythonOlder,
+}:
+buildPythonPackage rec {
+  pname = "mkdocs-awesome-pages-plugin";
+  version = "2.9.2";
+  pyproject = true;
+
+  disabled = pythonOlder "3.9";
+
+  src = fetchFromGitHub {
+    owner = "lukasgeiter";
+    repo = "mkdocs-awesome-pages-plugin";
+    rev = "refs/tags/v${version}";
+    hash = "sha256-pYyZ84eNrslxgLSBr3teQqmV7hA+LHwJ+Z99QgPdh6U=";
+  };
+
+  propagatedBuildInputs = [
+    mkdocs
+    wcmatch
+    natsort
+  ];
+
+  nativeBuildInputs = [poetry-core];
+
+  nativeCheckInputs = [
+    pytestCheckHook
+    beautifulsoup4
+    mock-open
+    importlib-metadata
+  ];
+
+  disabledTestPaths = [
+    # requires "generatedfiles" mkdocs plugin
+    "mkdocs_awesome_pages_plugin/tests/e2e/test_gen_files.py"
+  ];
+
+  meta = with lib; {
+    description = "An MkDocs plugin that simplifies configuring page titles and their order";
+    homepage = "https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin";
+    changelog = "https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/blob/v${version}/CHANGELOG";
+    license = licenses.mit;
+    maintainers = with maintainers; [phaer];
+  };
+}

From c67109b0f1d7d28430daf6ea9013c6475ef80dd1 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Thu, 13 Jun 2024 13:37:45 +0200
Subject: [PATCH 18/67] docs: add devShell hook

---
 modules/flake-parts/reference-website/default.nix | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/modules/flake-parts/reference-website/default.nix b/modules/flake-parts/reference-website/default.nix
index 9d2e47ae..4db5ec03 100644
--- a/modules/flake-parts/reference-website/default.nix
+++ b/modules/flake-parts/reference-website/default.nix
@@ -142,6 +142,15 @@
         packages = [
           pythonWithDeps
         ];
+
+        shellHook = ''
+          cd $PRJ_ROOT/docs
+          if [ ! -d src/reference ]; then
+            echo "linking .#reference to src/reference, you need to update this manually\
+            and remove it before a production build"
+            ln -s $(nix build ..#reference --no-link --print-out-paths) src/reference
+          fi
+        '';
       };
   };
 }

From 66d8e84cee772dede4466989627a961704e27c85 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Thu, 13 Jun 2024 13:38:03 +0200
Subject: [PATCH 19/67] docs: remove anchors warning

...because it's not yet supported in our mkdocs version
---
 docs/mkdocs.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 199044d3..11f22b3b 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -29,7 +29,6 @@ validation:
   omitted_files: warn
   absolute_links: warn
   unrecognized_links: warn
-  anchors: warn
 
 theme:
   name: material

From 318a87ff5550b6b4de35705e00f0b0f7940dd072 Mon Sep 17 00:00:00 2001
From: Yorick van Pelt <yorick@yorickvanpelt.nl>
Date: Wed, 18 Oct 2023 11:46:13 +0200
Subject: [PATCH 20/67] filter-pypi-responses: stream package requests that hit
 the proxy

mitmproxy was buffering all requests (except pythonhosted.*), causing
pip to time out when getting big packages from custom URLs.

Setting flow.response.stream in the responseheaders hook fixes this.
---
 pkgs/fetchPipMetadata/filter-pypi-responses.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/pkgs/fetchPipMetadata/filter-pypi-responses.py b/pkgs/fetchPipMetadata/filter-pypi-responses.py
index eea126be..4c188568 100644
--- a/pkgs/fetchPipMetadata/filter-pypi-responses.py
+++ b/pkgs/fetchPipMetadata/filter-pypi-responses.py
@@ -85,6 +85,11 @@ Response format:
 """
 
 
+def responseheaders(flow: http.HTTPFlow) -> None:
+    if "/simple/" not in flow.request.url:
+        flow.response.stream = True
+
+
 def response(flow: http.HTTPFlow) -> None:
     if not "/simple/" in flow.request.url:
         return

From b6bae07d51822c3ba2fceed14b4997fe5537f66e Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Thu, 13 Jun 2024 14:39:22 +0200
Subject: [PATCH 21/67] docs move options reference template to own file

---
 docs/hooks/render_options.py      | 58 ++++---------------------------
 docs/mkdocs.yml                   |  1 +
 docs/theme/reference_options.html | 37 ++++++++++++++++++++
 3 files changed, 44 insertions(+), 52 deletions(-)
 create mode 100644 docs/theme/reference_options.html

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
index 5f81352a..e166acd6 100644
--- a/docs/hooks/render_options.py
+++ b/docs/hooks/render_options.py
@@ -38,7 +38,9 @@ def preprocess_options(options):
     return tree
 
 
-def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, files: Files):
+def on_page_markdown(
+    markdown: str, page: Page, config: MkDocsConfig, files: Files
+) -> str | None:
     if not is_reference_page(page):
         return markdown
 
@@ -47,57 +49,9 @@ def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, files: Fil
     if not options_path.exists():
         log.error(f"{options_path} does not exist")
 
-    jinja = config.theme.get_env()
-    jinja.filters["slugify"] = slugify
-    options_template = jinja.from_string(
-        """
-## Options
-{%- for name, children in options.items() recursive %}
-
-##{{loop.depth * "#"}} {{ name }}
-
-{% if "type" in children -%}
-
-{{ children.description }}
-
-<table>
-    <tr>
-        <td>type</td>
-        <td><code>{{ children.type }}</code> {{ "(read only)" if children.readOnly else "" }}</td>
-    </tr>
-    <tr>
-        <td>source</td>
-        <td>{%- for d in children.declarations -%}<a href="{{d.url}}">{{d.name}}</a>{{ ", " if not loop.last else "" }}{%- endfor -%}</td>
-    </tr>
-    {%- if children.default -%}
-    <tr>
-        <td>default</td>
-        <td><pre>{{(children.default | default({})).text}}</pre></td>
-    </tr>
-    {%- endif -%}
-    {%- if children.exampl -%}
-    <tr>
-        <td>example</td>
-        <td>
-                <pre>{{(children.example | default({})).text | replace("\n", "\\n")}}</pre>
-    </td>
-    </tr>
-    {%- endif -%}
-</table>
-
-{#
-```json
-{{ children | tojson(indent=2)}}
-```
-#}
-
-{%- else -%}
-{{ loop(children.items()) }}
-{%- endif %}
-{%- endfor %}
-"""
-    )
-
+    env = config.theme.get_env()
+    env.filters["slugify"] = slugify
+    options_template = env.get_template("reference_options.html")
     with open(options_path, "r") as f:
         options = json.load(f)
 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 11f22b3b..025673b2 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -31,6 +31,7 @@ validation:
   unrecognized_links: warn
 
 theme:
+  custom_dir: theme
   name: material
   favicon: favicon.png
   logo: favicon.png
diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
new file mode 100644
index 00000000..38f6e847
--- /dev/null
+++ b/docs/theme/reference_options.html
@@ -0,0 +1,37 @@
+## Options
+{%- for name, children in options.items() recursive %}
+
+##{{loop.depth * "#"}} {{ name }}
+
+{% if "type" in children -%}
+
+{{ children.description }}
+
+<table>
+    <tr>
+        <td>type</td>
+        <td><code>{{ children.type }}</code> {{ "(read only)" if children.readOnly else "" }}</td>
+    </tr>
+    <tr>
+        <td>source</td>
+        <td>{%- for d in children.declarations -%}<a href="{{d.url}}">{{d.name}}</a>{{ ", " if not loop.last else "" }}{%- endfor -%}</td>
+    </tr>
+    {%- if children.default -%}
+    <tr>
+        <td>default</td>
+        <td><pre>{{(children.default | default({})).text}}</pre></td>
+    </tr>
+    {%- endif -%}
+    {%- if children.exampl -%}
+    <tr>
+        <td>example</td>
+        <td>
+            <pre>{{(children.example | default({})).text | replace("\n", "\\n")}}</pre>
+        </td>
+    </tr>
+    {%- endif -%}
+</table>
+{%- else -%}
+{{ loop(children.items()) }}
+{%- endif %}
+{%- endfor %}

From 9dba824ae8ef323dc7ec0ff8ec6d8d0ad330befa Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Thu, 13 Jun 2024 15:23:15 +0200
Subject: [PATCH 22/67] docs: add reference header

---
 docs/hooks/render_options.py     | 17 ++++++++---------
 docs/theme/reference_header.html | 16 ++++++++++++++++
 modules/dream2nix/pip/README.md  |  6 +++---
 3 files changed, 27 insertions(+), 12 deletions(-)
 create mode 100644 docs/theme/reference_header.html

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
index e166acd6..ddc7dbc5 100644
--- a/docs/hooks/render_options.py
+++ b/docs/hooks/render_options.py
@@ -43,18 +43,17 @@ def on_page_markdown(
 ) -> str | None:
     if not is_reference_page(page):
         return markdown
-
     src_path = Path(config.docs_dir) / page.file.src_path
+    env = config.theme.get_env()
+
+    header = env.get_template("reference_header.html").render(meta=page.meta)
+
     options_path = src_path.parent / "options.json"
     if not options_path.exists():
         log.error(f"{options_path} does not exist")
-
-    env = config.theme.get_env()
-    env.filters["slugify"] = slugify
-    options_template = env.get_template("reference_options.html")
+        return None
     with open(options_path, "r") as f:
-        options = json.load(f)
+        options = preprocess_options(json.load(f))
+    reference = env.get_template("reference_options.html").render(options=options)
 
-    tree = preprocess_options(options)
-    rendered = options_template.render(options=tree)
-    return markdown + rendered
+    return "\n\n".join([header, markdown, reference])
diff --git a/docs/theme/reference_header.html b/docs/theme/reference_header.html
new file mode 100644
index 00000000..7e9b3961
--- /dev/null
+++ b/docs/theme/reference_header.html
@@ -0,0 +1,16 @@
+<table style="float: right;">
+    <tr>
+        <td>state:</td>
+        <td>{{ meta.state | default("experimental") }}</td>
+    </tr>
+    <tr>
+        <td>maintainers:</td>
+        <td>
+            {% if meta.maintainers -%}
+            {% for m in meta.maintainers -%}<a href="https://github.com/{{m}}">@{{m}}</a>{{ ", " if not loop.last else "" }}{%- endfor -%}
+            {%- else -%}
+            noone, maybe <strong>you</strong>?
+            {% endif %}
+        </td>
+    </tr>
+</table>
diff --git a/modules/dream2nix/pip/README.md b/modules/dream2nix/pip/README.md
index 94db4aed..d5f05f5b 100644
--- a/modules/dream2nix/pip/README.md
+++ b/modules/dream2nix/pip/README.md
@@ -1,8 +1,8 @@
 ---
+title: "pip"
 state: released
-maintainers: @phaer
+maintainers:
+  - phaer
 ---
 
-# pip
-
 Python packaging via [pip](https://pip.pypa.io/).

From a35e43c84c8acff4ae1aeb948b7651e64567f017 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Thu, 13 Jun 2024 15:47:32 +0200
Subject: [PATCH 23/67] docs: add missing readmes

(auto generated)
---
 modules/dream2nix/WIP-groups/README.md               | 7 +++++++
 modules/dream2nix/WIP-haskell-cabal/README.md        | 6 ++++++
 modules/dream2nix/WIP-nodejs-builder-v3/README.md    | 6 ++++++
 modules/dream2nix/WIP-python-pdm/README.md           | 6 ++++++
 modules/dream2nix/WIP-python-pyproject/README.md     | 6 ++++++
 modules/dream2nix/WIP-spago/README.md                | 6 ++++++
 modules/dream2nix/buildPythonPackage/README.md       | 6 ++++++
 modules/dream2nix/buildRustPackage/README.md         | 6 ++++++
 modules/dream2nix/builtins-derivation/README.md      | 6 ++++++
 modules/dream2nix/core/README.md                     | 6 ++++++
 modules/dream2nix/mkDerivation/README.md             | 7 +++++++
 modules/dream2nix/multi-derivation-package/README.md | 6 ++++++
 modules/dream2nix/nixpkgs-overrides/README.md        | 6 ++++++
 modules/dream2nix/nodejs-devshell-v3/README.md       | 6 ++++++
 modules/dream2nix/nodejs-devshell/README.md          | 6 ++++++
 modules/dream2nix/nodejs-granular-v3/README.md       | 6 ++++++
 modules/dream2nix/nodejs-granular/README.md          | 6 ++++++
 modules/dream2nix/nodejs-node-modules-v3/README.md   | 6 ++++++
 modules/dream2nix/nodejs-node-modules/README.md      | 6 ++++++
 modules/dream2nix/nodejs-package-json-v3/README.md   | 6 ++++++
 modules/dream2nix/nodejs-package-json/README.md      | 6 ++++++
 modules/dream2nix/nodejs-package-lock-v3/README.md   | 6 ++++++
 modules/dream2nix/nodejs-package-lock/README.md      | 6 ++++++
 modules/dream2nix/overrides/README.md                | 6 ++++++
 modules/dream2nix/package-func/README.md             | 6 ++++++
 modules/dream2nix/php-composer-lock/README.md        | 6 ++++++
 modules/dream2nix/php-granular/README.md             | 6 ++++++
 modules/dream2nix/rust-cargo-lock/README.md          | 6 ++++++
 modules/dream2nix/rust-crane/README.md               | 6 ++++++
 29 files changed, 176 insertions(+)
 create mode 100644 modules/dream2nix/WIP-haskell-cabal/README.md
 create mode 100644 modules/dream2nix/WIP-nodejs-builder-v3/README.md
 create mode 100644 modules/dream2nix/WIP-python-pdm/README.md
 create mode 100644 modules/dream2nix/WIP-python-pyproject/README.md
 create mode 100644 modules/dream2nix/WIP-spago/README.md
 create mode 100644 modules/dream2nix/buildPythonPackage/README.md
 create mode 100644 modules/dream2nix/buildRustPackage/README.md
 create mode 100644 modules/dream2nix/builtins-derivation/README.md
 create mode 100644 modules/dream2nix/core/README.md
 create mode 100644 modules/dream2nix/multi-derivation-package/README.md
 create mode 100644 modules/dream2nix/nixpkgs-overrides/README.md
 create mode 100644 modules/dream2nix/nodejs-devshell-v3/README.md
 create mode 100644 modules/dream2nix/nodejs-devshell/README.md
 create mode 100644 modules/dream2nix/nodejs-granular-v3/README.md
 create mode 100644 modules/dream2nix/nodejs-granular/README.md
 create mode 100644 modules/dream2nix/nodejs-node-modules-v3/README.md
 create mode 100644 modules/dream2nix/nodejs-node-modules/README.md
 create mode 100644 modules/dream2nix/nodejs-package-json-v3/README.md
 create mode 100644 modules/dream2nix/nodejs-package-json/README.md
 create mode 100644 modules/dream2nix/nodejs-package-lock-v3/README.md
 create mode 100644 modules/dream2nix/nodejs-package-lock/README.md
 create mode 100644 modules/dream2nix/overrides/README.md
 create mode 100644 modules/dream2nix/package-func/README.md
 create mode 100644 modules/dream2nix/php-composer-lock/README.md
 create mode 100644 modules/dream2nix/php-granular/README.md
 create mode 100644 modules/dream2nix/rust-cargo-lock/README.md
 create mode 100644 modules/dream2nix/rust-crane/README.md

diff --git a/modules/dream2nix/WIP-groups/README.md b/modules/dream2nix/WIP-groups/README.md
index d3d0b75f..08981c28 100644
--- a/modules/dream2nix/WIP-groups/README.md
+++ b/modules/dream2nix/WIP-groups/README.md
@@ -1,3 +1,10 @@
+---
+title: "groups"
+state: experimental
+maintainers:
+  - DavHau
+---
+
 Module to deal with package sets (so called groups in dream2nix)
 
 ## Separate different kinds of dependencies
diff --git a/modules/dream2nix/WIP-haskell-cabal/README.md b/modules/dream2nix/WIP-haskell-cabal/README.md
new file mode 100644
index 00000000..791aa78c
--- /dev/null
+++ b/modules/dream2nix/WIP-haskell-cabal/README.md
@@ -0,0 +1,6 @@
+---
+title: "haskell-cabal"
+state: "experimental"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/WIP-nodejs-builder-v3/README.md b/modules/dream2nix/WIP-nodejs-builder-v3/README.md
new file mode 100644
index 00000000..2389e1ed
--- /dev/null
+++ b/modules/dream2nix/WIP-nodejs-builder-v3/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-builder-v3"
+state: "experimental"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/WIP-python-pdm/README.md b/modules/dream2nix/WIP-python-pdm/README.md
new file mode 100644
index 00000000..d58ad83d
--- /dev/null
+++ b/modules/dream2nix/WIP-python-pdm/README.md
@@ -0,0 +1,6 @@
+---
+title: "python-pdm"
+state: "experimental"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/WIP-python-pyproject/README.md b/modules/dream2nix/WIP-python-pyproject/README.md
new file mode 100644
index 00000000..f74954af
--- /dev/null
+++ b/modules/dream2nix/WIP-python-pyproject/README.md
@@ -0,0 +1,6 @@
+---
+title: "python-pyproject"
+state: "experimental"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/WIP-spago/README.md b/modules/dream2nix/WIP-spago/README.md
new file mode 100644
index 00000000..2ed0df89
--- /dev/null
+++ b/modules/dream2nix/WIP-spago/README.md
@@ -0,0 +1,6 @@
+---
+title: "spago"
+state: "experimental"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/buildPythonPackage/README.md b/modules/dream2nix/buildPythonPackage/README.md
new file mode 100644
index 00000000..d8cd414e
--- /dev/null
+++ b/modules/dream2nix/buildPythonPackage/README.md
@@ -0,0 +1,6 @@
+---
+title: "buildPythonPackage"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/buildRustPackage/README.md b/modules/dream2nix/buildRustPackage/README.md
new file mode 100644
index 00000000..d3d9d323
--- /dev/null
+++ b/modules/dream2nix/buildRustPackage/README.md
@@ -0,0 +1,6 @@
+---
+title: "buildRustPackage"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/builtins-derivation/README.md b/modules/dream2nix/builtins-derivation/README.md
new file mode 100644
index 00000000..06c573c5
--- /dev/null
+++ b/modules/dream2nix/builtins-derivation/README.md
@@ -0,0 +1,6 @@
+---
+title: "builtins-derivation"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/core/README.md b/modules/dream2nix/core/README.md
new file mode 100644
index 00000000..5fc91cc0
--- /dev/null
+++ b/modules/dream2nix/core/README.md
@@ -0,0 +1,6 @@
+---
+title: "core"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/mkDerivation/README.md b/modules/dream2nix/mkDerivation/README.md
index afec0723..2367d7a6 100644
--- a/modules/dream2nix/mkDerivation/README.md
+++ b/modules/dream2nix/mkDerivation/README.md
@@ -1 +1,8 @@
+---
+title: "mkDerivation"
+state: released
+maintainers:
+  - DavHau
+---
+
 A package module based on the mkDerivation builder from nixpkgs
diff --git a/modules/dream2nix/multi-derivation-package/README.md b/modules/dream2nix/multi-derivation-package/README.md
new file mode 100644
index 00000000..7c4da57e
--- /dev/null
+++ b/modules/dream2nix/multi-derivation-package/README.md
@@ -0,0 +1,6 @@
+---
+title: "multi-derivation-package"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nixpkgs-overrides/README.md b/modules/dream2nix/nixpkgs-overrides/README.md
new file mode 100644
index 00000000..97b1458f
--- /dev/null
+++ b/modules/dream2nix/nixpkgs-overrides/README.md
@@ -0,0 +1,6 @@
+---
+title: "nixpkgs-overrides"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-devshell-v3/README.md b/modules/dream2nix/nodejs-devshell-v3/README.md
new file mode 100644
index 00000000..6c2abeec
--- /dev/null
+++ b/modules/dream2nix/nodejs-devshell-v3/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-devshell-v3"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-devshell/README.md b/modules/dream2nix/nodejs-devshell/README.md
new file mode 100644
index 00000000..cb91d6e6
--- /dev/null
+++ b/modules/dream2nix/nodejs-devshell/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-devshell"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-granular-v3/README.md b/modules/dream2nix/nodejs-granular-v3/README.md
new file mode 100644
index 00000000..01a661b6
--- /dev/null
+++ b/modules/dream2nix/nodejs-granular-v3/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-granular-v3"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-granular/README.md b/modules/dream2nix/nodejs-granular/README.md
new file mode 100644
index 00000000..7ec20d0e
--- /dev/null
+++ b/modules/dream2nix/nodejs-granular/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-granular"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-node-modules-v3/README.md b/modules/dream2nix/nodejs-node-modules-v3/README.md
new file mode 100644
index 00000000..487413ef
--- /dev/null
+++ b/modules/dream2nix/nodejs-node-modules-v3/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-node-modules-v3"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-node-modules/README.md b/modules/dream2nix/nodejs-node-modules/README.md
new file mode 100644
index 00000000..a89169a1
--- /dev/null
+++ b/modules/dream2nix/nodejs-node-modules/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-node-modules"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-package-json-v3/README.md b/modules/dream2nix/nodejs-package-json-v3/README.md
new file mode 100644
index 00000000..6dd67449
--- /dev/null
+++ b/modules/dream2nix/nodejs-package-json-v3/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-package-json-v3"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-package-json/README.md b/modules/dream2nix/nodejs-package-json/README.md
new file mode 100644
index 00000000..e3d657af
--- /dev/null
+++ b/modules/dream2nix/nodejs-package-json/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-package-json"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-package-lock-v3/README.md b/modules/dream2nix/nodejs-package-lock-v3/README.md
new file mode 100644
index 00000000..51bb23d3
--- /dev/null
+++ b/modules/dream2nix/nodejs-package-lock-v3/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-package-lock-v3"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/nodejs-package-lock/README.md b/modules/dream2nix/nodejs-package-lock/README.md
new file mode 100644
index 00000000..afd6b2e6
--- /dev/null
+++ b/modules/dream2nix/nodejs-package-lock/README.md
@@ -0,0 +1,6 @@
+---
+title: "nodejs-package-lock"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/overrides/README.md b/modules/dream2nix/overrides/README.md
new file mode 100644
index 00000000..21561c3d
--- /dev/null
+++ b/modules/dream2nix/overrides/README.md
@@ -0,0 +1,6 @@
+---
+title: "overrides"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/package-func/README.md b/modules/dream2nix/package-func/README.md
new file mode 100644
index 00000000..3075eb87
--- /dev/null
+++ b/modules/dream2nix/package-func/README.md
@@ -0,0 +1,6 @@
+---
+title: "package-func"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/php-composer-lock/README.md b/modules/dream2nix/php-composer-lock/README.md
new file mode 100644
index 00000000..3b887207
--- /dev/null
+++ b/modules/dream2nix/php-composer-lock/README.md
@@ -0,0 +1,6 @@
+---
+title: "php-composer-lock"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/php-granular/README.md b/modules/dream2nix/php-granular/README.md
new file mode 100644
index 00000000..f8a38186
--- /dev/null
+++ b/modules/dream2nix/php-granular/README.md
@@ -0,0 +1,6 @@
+---
+title: "php-granular"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/rust-cargo-lock/README.md b/modules/dream2nix/rust-cargo-lock/README.md
new file mode 100644
index 00000000..a027d6fd
--- /dev/null
+++ b/modules/dream2nix/rust-cargo-lock/README.md
@@ -0,0 +1,6 @@
+---
+title: "rust-cargo-lock"
+state: "released"
+maintainers:
+  - DavHau
+---
diff --git a/modules/dream2nix/rust-crane/README.md b/modules/dream2nix/rust-crane/README.md
new file mode 100644
index 00000000..20ea5fcf
--- /dev/null
+++ b/modules/dream2nix/rust-crane/README.md
@@ -0,0 +1,6 @@
+---
+title: "rust-crane"
+state: "released"
+maintainers:
+  - DavHau
+---

From 8aa4a44eaf2df83f504e9fd56809f8407f642672 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Fri, 14 Jun 2024 12:23:10 +0200
Subject: [PATCH 24/67] docs: link github repo

---
 docs/mkdocs.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 025673b2..9ad33326 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -3,6 +3,10 @@ docs_dir: "src"
 site_url: "https://nix-community.github.io/dream2nix"
 site_dir: !ENV out
 
+repo_url: https://github.com/nix-community/dream2nix
+repo_name: nix-community/dream2nix
+edit_uri: edit/main/docs/src/
+
 plugins:
   - search
   - awesome-pages

From 32023d41ed6e8daee6910996b2c84dad5f04388b Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Fri, 14 Jun 2024 13:39:41 +0200
Subject: [PATCH 25/67] docs: enable permalink links for headings

---
 docs/mkdocs.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 9ad33326..e0b0ec09 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -18,6 +18,8 @@ extra_css:
   - style.css
 
 markdown_extensions:
+  - toc:
+      permalink: true
   - tables
   - admonition
   - pymdownx.escapeall

From ea02037ba9c4c3e7e1722b784c961acb2aca6a9c Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Fri, 14 Jun 2024 13:40:08 +0200
Subject: [PATCH 26/67] docs: force symlinks for src/reference

---
 modules/flake-parts/reference-website/default.nix | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/modules/flake-parts/reference-website/default.nix b/modules/flake-parts/reference-website/default.nix
index 4db5ec03..a513a832 100644
--- a/modules/flake-parts/reference-website/default.nix
+++ b/modules/flake-parts/reference-website/default.nix
@@ -106,7 +106,7 @@
         ];
       } ''
         cp -rL --no-preserve=mode  ${dream2nixRoot}/docs/* .
-        ln -s ${referenceDocs} ./src/reference
+        ln -sfT ${referenceDocs} ./src/reference
         mkdocs build
       '';
   in {
@@ -148,7 +148,7 @@
           if [ ! -d src/reference ]; then
             echo "linking .#reference to src/reference, you need to update this manually\
             and remove it before a production build"
-            ln -s $(nix build ..#reference --no-link --print-out-paths) src/reference
+            ln -sfT $(nix build ..#reference --no-link --print-out-paths) src/reference
           fi
         '';
       };

From 361f402625a2fde1e0d57690378633bfb9a5dde0 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Fri, 14 Jun 2024 14:27:49 +0200
Subject: [PATCH 27/67] docs: s/reference(Docs)?/optionsReference/

---
 modules/flake-parts/reference-website/default.nix | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/modules/flake-parts/reference-website/default.nix b/modules/flake-parts/reference-website/default.nix
index a513a832..f6720a9b 100644
--- a/modules/flake-parts/reference-website/default.nix
+++ b/modules/flake-parts/reference-website/default.nix
@@ -74,7 +74,7 @@
       inherit modules;
     };
 
-    referenceDocs = let
+    optionsReference = let
       publicModules =
         lib.filterAttrs
         (n: v: lib.pathExists (v + "/README.md"))
@@ -102,11 +102,11 @@
           pkgs.python3.pkgs.mkdocs
           pkgs.python3.pkgs.mkdocs-material
           self.packages.${system}.mkdocs-awesome-pages-plugin
-          referenceDocs
+          optionsReference
         ];
       } ''
         cp -rL --no-preserve=mode  ${dream2nixRoot}/docs/* .
-        ln -sfT ${referenceDocs} ./src/reference
+        ln -sfT ${optionsReference} ./src/reference
         mkdocs build
       '';
   in {
@@ -125,7 +125,7 @@
         pythonOlder
         ;
     };
-    packages.reference = referenceDocs;
+    packages.optionsReference = optionsReference;
     packages.website = website;
     devShells.website = let
       pythonWithDeps = pkgs.python3.withPackages (

From b80a263443d9dc7b755645f3db3b62efb85b2ab0 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Fri, 14 Jun 2024 14:28:30 +0200
Subject: [PATCH 28/67] add docs/README.md

---
 docs/README.md   | 67 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/src/.pages  |  1 +
 docs/src/docs.md |  1 +
 3 files changed, 69 insertions(+)
 create mode 100644 docs/README.md
 create mode 120000 docs/src/docs.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..ac59c302
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,67 @@
+# About this Documentation
+
+Dream2nix documentation is generated from markdown via 
+[mkdocs](https://www.mkdocs.org/) and [mkdocs-material](https://squidfunk.github.io/mkdocs-material/).
+
+## Build
+
+You can build and server it locally with, i.e.:
+
+``` shellsession
+nix build .#website
+python3 -m http.server -d ./result
+```
+
+# Development shell
+
+Or alternatively run a development environment with:
+
+``` shellsession
+nix develop .#website
+```
+
+Upon entering the devshell, it will change into
+`./docs` and symlink a build of the [options reference](#options-reference)
+into `./docs/src/reference`. 
+
+Normal builds will always use an up-to-date options reference,
+but during development you need to update this symlink yourself
+and remove it after use. 
+
+i.e. from inside the shell in `./docs`:
+
+``` shellsession
+# update
+ln -sfT $(nix build --print-out-paths --no-link ..#reference) ./src/reference
+# remove
+rm ./src/reference
+```
+
+## Options Reference
+
+The reference documentation for [modules](./modules.md) is auto-generated via
+a custom hook in `docs/hooks/render_options.py` and a derivation in
+`.#optionsReference`. 
+
+The derivation includes, for each module, an `options.json` file as generated by nix via `pkgs.nixosOptionsDoc` as well as a `README.md` file, copied from the modules source directory. The existence of such a `README.md` is used as an indicator on whether to include a module in the reference documentation.
+
+The hook runs whenever mkdocs renders one of the `README.md`s. Each of them gets concatenated with header and options reference, after the latter are run through jinja templates in `./docs/theme`.
+
+
+## Notes on Markdown
+
+Mkdocs uses a markdown dialect from [Python-Markdown](https://python-markdown.github.io/) with various, optional extensions listed in `./docs/mkdocs.yml`.
+
+This is different from the CommonMark dialect, as implemented by [markdown-it-py](https://pypi.org/project/markdown-it-py/) and used in NixOS official documentation.
+
+The differences between both don't seem to be too relevant for the markdown features used in our [options reference](#options-reference), but it's good
+to be aware of them when writing longer prose.
+
+[mkdocs-materials reference](https://squidfunk.github.io/mkdocs-material/reference) provides a
+good overview on useful extensions.
+
+## CI
+
+The documentation is published on GitHub pages via a GitHub action, defined in [.github/workflows/pages.yml](https://github.com/nix-community/dream2nix/blob/main/.github/workflows/pages.yml)
+
+    
diff --git a/docs/src/.pages b/docs/src/.pages
index a6cbad31..717f945a 100644
--- a/docs/src/.pages
+++ b/docs/src/.pages
@@ -9,6 +9,7 @@ nav:
       - "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
       - "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
       - "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
+  - Documentation: docs.md
   - Notes:
     - "v1 API design docs": v1-api
     - development-roundups
diff --git a/docs/src/docs.md b/docs/src/docs.md
new file mode 120000
index 00000000..32d46ee8
--- /dev/null
+++ b/docs/src/docs.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file

From d8100dc310dc967acfd76271c94afeec2a5fa1fc Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Fri, 14 Jun 2024 14:28:40 +0200
Subject: [PATCH 29/67] add docs/src/reference to .gitignore

---
 .gitignore | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 61d8e51f..baa520fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,4 +5,6 @@
 result
 interpreter
 __pycache__
-*.egg-info
\ No newline at end of file
+*.egg-info
+# symlink for devshell
+docs/src/reference

From 4266fcc0abd67af6f4a5aa11a77fe81c64a00437 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Fri, 14 Jun 2024 15:31:43 +0200
Subject: [PATCH 30/67] docs: fix typo

---
 docs/theme/reference_options.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
index 38f6e847..65aed766 100644
--- a/docs/theme/reference_options.html
+++ b/docs/theme/reference_options.html
@@ -22,7 +22,7 @@
         <td><pre>{{(children.default | default({})).text}}</pre></td>
     </tr>
     {%- endif -%}
-    {%- if children.exampl -%}
+    {%- if children.example -%}
     <tr>
         <td>example</td>
         <td>

From d4c77a62d66a2df512b2bd5259fea3275a1db4e5 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Fri, 14 Jun 2024 15:32:42 +0200
Subject: [PATCH 31/67] docs: children -> option

---
 docs/README.md                    |  2 +-
 docs/theme/reference_options.html | 20 ++++++++++----------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index ac59c302..7f02c62d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -32,7 +32,7 @@ i.e. from inside the shell in `./docs`:
 
 ``` shellsession
 # update
-ln -sfT $(nix build --print-out-paths --no-link ..#reference) ./src/reference
+ln -sfT $(nix build --print-out-paths --no-link ..#optionsReference) ./src/reference
 # remove
 rm ./src/reference
 ```
diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
index 65aed766..178b2005 100644
--- a/docs/theme/reference_options.html
+++ b/docs/theme/reference_options.html
@@ -1,37 +1,37 @@
 ## Options
-{%- for name, children in options.items() recursive %}
+{%- for name, option in options.items() recursive %}
 
 ##{{loop.depth * "#"}} {{ name }}
 
-{% if "type" in children -%}
+{% if "type" in option -%}
 
-{{ children.description }}
+{{ option.description }}
 
 <table>
     <tr>
         <td>type</td>
-        <td><code>{{ children.type }}</code> {{ "(read only)" if children.readOnly else "" }}</td>
+        <td><code>{{ option.type }}</code> {{ "(read only)" if option.readOnly else "" }}</td>
     </tr>
     <tr>
         <td>source</td>
-        <td>{%- for d in children.declarations -%}<a href="{{d.url}}">{{d.name}}</a>{{ ", " if not loop.last else "" }}{%- endfor -%}</td>
+        <td>{%- for d in option.declarations -%}<a href="{{d.url}}">{{d.name}}</a>{{ ", " if not loop.last else "" }}{%- endfor -%}</td>
     </tr>
-    {%- if children.default -%}
+    {%- if option.default -%}
     <tr>
         <td>default</td>
-        <td><pre>{{(children.default | default({})).text}}</pre></td>
+        <td><pre>{{(option.default | default({})).text}}</pre></td>
     </tr>
     {%- endif -%}
-    {%- if children.example -%}
+    {%- if option.example -%}
     <tr>
         <td>example</td>
         <td>
-            <pre>{{(children.example | default({})).text | replace("\n", "\\n")}}</pre>
+            <pre>{{(option.example | default({})).text | replace("\n", "\\n")}}</pre>
         </td>
     </tr>
     {%- endif -%}
 </table>
 {%- else -%}
-{{ loop(children.items()) }}
+{{ loop(option.items()) }}
 {%- endif %}
 {%- endfor %}

From f2f428f7584951a2ca5e0fa07ff02be9120729a9 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Sat, 15 Jun 2024 11:53:27 +0200
Subject: [PATCH 32/67] docs: add extra header to reference docs

---
 docs/theme/reference_header.html | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/theme/reference_header.html b/docs/theme/reference_header.html
index 7e9b3961..9ab861ba 100644
--- a/docs/theme/reference_header.html
+++ b/docs/theme/reference_header.html
@@ -14,3 +14,5 @@
         </td>
     </tr>
 </table>
+
+## Introduction

From 8cf6639c8ba67caff0e19efd979aafc24c7ff83d Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Sat, 15 Jun 2024 20:34:53 +0200
Subject: [PATCH 33/67] docs: fix missing options of submodules

---
 docs/hooks/render_options.py      |  9 ++++-----
 docs/theme/reference_options.html | 10 +++++-----
 2 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
index ddc7dbc5..be3f194c 100644
--- a/docs/hooks/render_options.py
+++ b/docs/hooks/render_options.py
@@ -19,7 +19,7 @@ def slugify(name: str) -> str:
 
 
 def preprocess_options(options):
-    tree = {}
+    tree = dict()
     for name, option in options.items():
         if name.startswith("_module"):
             continue
@@ -28,13 +28,12 @@ def preprocess_options(options):
         for index, part in enumerate(parts):
             if part not in cursor:
                 if index + 1 == len(parts):
-                    cursor[part] = option
+                    cursor[part] = dict(**option, children={})
                 else:
-                    cursor[part] = dict()
+                    cursor[part] = dict(children=dict())
                     cursor = cursor[part]
             else:
-                cursor = cursor[part]
-
+                cursor = cursor[part]["children"]
     return tree
 
 
diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
index 178b2005..de3c9a25 100644
--- a/docs/theme/reference_options.html
+++ b/docs/theme/reference_options.html
@@ -3,10 +3,9 @@
 
 ##{{loop.depth * "#"}} {{ name }}
 
-{% if "type" in option -%}
-
-{{ option.description }}
+{{ option.description or '' }}
 
+{% if "type" in option %}
 <table>
     <tr>
         <td>type</td>
@@ -31,7 +30,8 @@
     </tr>
     {%- endif -%}
 </table>
-{%- else -%}
-{{ loop(option.items()) }}
+{% endif %}
+{%- if option.children -%}
+{{ loop(option.children.items()) }}
 {%- endif %}
 {%- endfor %}

From 7aca3e34ff2dce7810e5662c8224ad123c41a812 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Sun, 16 Jun 2024 13:35:07 +0200
Subject: [PATCH 34/67] docs: fix rendering of examples

---
 docs/theme/reference_options.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
index de3c9a25..c236be83 100644
--- a/docs/theme/reference_options.html
+++ b/docs/theme/reference_options.html
@@ -25,7 +25,7 @@
     <tr>
         <td>example</td>
         <td>
-            <pre>{{(option.example | default({})).text | replace("\n", "\\n")}}</pre>
+            <pre>{{(option.example | default({})).text}}</pre>
         </td>
     </tr>
     {%- endif -%}

From df887721f78c460ae33542a3c7febc68e7524721 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Sun, 16 Jun 2024 14:39:21 +0200
Subject: [PATCH 35/67] reference options: escape < and >

---
 docs/theme/reference_options.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
index c236be83..a176efc6 100644
--- a/docs/theme/reference_options.html
+++ b/docs/theme/reference_options.html
@@ -1,7 +1,7 @@
 ## Options
 {%- for name, option in options.items() recursive %}
 
-##{{loop.depth * "#"}} {{ name }}
+##{{loop.depth * "#"}} {{ name.replace("<", "&lt;").replace(">", "&gt;") }}
 
 {{ option.description or '' }}
 

From e62c7b759abc563ec6b26c5fbdcefdce82e2876c Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Sun, 16 Jun 2024 14:39:49 +0200
Subject: [PATCH 36/67] docs: custom sort for rendered options

---
 docs/hooks/render_options.py | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
index be3f194c..a4d4a218 100644
--- a/docs/hooks/render_options.py
+++ b/docs/hooks/render_options.py
@@ -1,6 +1,8 @@
 import logging
 import json
 from pathlib import Path
+from collections import OrderedDict
+from typing import Dict, Tuple
 
 from mkdocs.structure.pages import Page
 from mkdocs.structure.files import Files
@@ -18,6 +20,20 @@ def slugify(name: str) -> str:
     return name.lower().replace(".", "-")
 
 
+def sort_options(item: Tuple[str, Dict]):
+    """
+    Sort the modules. First the one the page is about,
+    then single options, then the rest, alphabetically
+    """
+    name, option = item
+    if name == "pip":
+        return -1
+    elif len(option["children"]) == 0:
+        return 0
+    else:
+        return ord(name[0])
+
+
 def preprocess_options(options):
     tree = dict()
     for name, option in options.items():
@@ -34,7 +50,7 @@ def preprocess_options(options):
                     cursor = cursor[part]
             else:
                 cursor = cursor[part]["children"]
-    return tree
+    return OrderedDict(sorted(tree.items(), key=sort_options))
 
 
 def on_page_markdown(

From 4175449e9380c0f7f433ca78bce5fd0918c0fac1 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 09:10:48 +0200
Subject: [PATCH 37/67] docs: syntax highlighting in reference

---
 docs/hooks/render_options.py      | 10 ++++++++--
 docs/theme/reference_options.html |  4 ++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
index a4d4a218..64b1f9d5 100644
--- a/docs/hooks/render_options.py
+++ b/docs/hooks/render_options.py
@@ -9,6 +9,11 @@ from mkdocs.structure.files import Files
 from mkdocs.config.defaults import MkDocsConfig
 
 
+from pygments import highlight
+from pygments.lexers import get_lexer_by_name
+from pygments.formatters import HtmlFormatter
+
+
 log = logging.getLogger("mkdocs")
 
 
@@ -16,8 +21,8 @@ def is_reference_page(page: Page) -> bool:
     return page.file.src_path.startswith("reference/")
 
 
-def slugify(name: str) -> str:
-    return name.lower().replace(".", "-")
+def pygments(code: str, lang: str) -> str:
+    return highlight(code, get_lexer_by_name(lang), HtmlFormatter())
 
 
 def sort_options(item: Tuple[str, Dict]):
@@ -60,6 +65,7 @@ def on_page_markdown(
         return markdown
     src_path = Path(config.docs_dir) / page.file.src_path
     env = config.theme.get_env()
+    env.filters["pygments"] = pygments
 
     header = env.get_template("reference_header.html").render(meta=page.meta)
 
diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
index a176efc6..bcf91490 100644
--- a/docs/theme/reference_options.html
+++ b/docs/theme/reference_options.html
@@ -18,14 +18,14 @@
     {%- if option.default -%}
     <tr>
         <td>default</td>
-        <td><pre>{{(option.default | default({})).text}}</pre></td>
+        <td><pre>{{(option.default | default({})).text | pygments("nix")}}</pre></td>
     </tr>
     {%- endif -%}
     {%- if option.example -%}
     <tr>
         <td>example</td>
         <td>
-            <pre>{{(option.example | default({})).text}}</pre>
+            <pre>{{(option.example | default({})).text | pygments("nix")}}</pre>
         </td>
     </tr>
     {%- endif -%}

From 855cfa5e77a069996f0ad61439e56da40f7c2c3f Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 09:11:18 +0200
Subject: [PATCH 38/67] docs: fix display of collapsible sidebar items

---
 docs/src/style.css | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/src/style.css b/docs/src/style.css
index 899bf2d7..4e3b12e6 100644
--- a/docs/src/style.css
+++ b/docs/src/style.css
@@ -2,3 +2,7 @@
     background-color: white;
     border-radius: 100%;
 }
+
+[data-md-component="toc"] .md-nav__link {
+    display: inline-flex;
+}

From b4ceedaafd680b60183fcc13770c282904ad2b8a Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 10:46:22 +0200
Subject: [PATCH 39/67] docs: fix sorting, don't hardcode pip ;)

---
 docs/hooks/render_options.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
index 64b1f9d5..76c189e4 100644
--- a/docs/hooks/render_options.py
+++ b/docs/hooks/render_options.py
@@ -25,13 +25,13 @@ def pygments(code: str, lang: str) -> str:
     return highlight(code, get_lexer_by_name(lang), HtmlFormatter())
 
 
-def sort_options(item: Tuple[str, Dict]):
+def sort_options(item: Tuple[str, Dict], module_name: str) -> int:
     """
     Sort the modules. First the one the page is about,
     then single options, then the rest, alphabetically
     """
     name, option = item
-    if name == "pip":
+    if name == module_name:
         return -1
     elif len(option["children"]) == 0:
         return 0
@@ -39,7 +39,7 @@ def sort_options(item: Tuple[str, Dict]):
         return ord(name[0])
 
 
-def preprocess_options(options):
+def preprocess_options(options, module_name):
     tree = dict()
     for name, option in options.items():
         if name.startswith("_module"):
@@ -55,7 +55,7 @@ def preprocess_options(options):
                     cursor = cursor[part]
             else:
                 cursor = cursor[part]["children"]
-    return OrderedDict(sorted(tree.items(), key=sort_options))
+    return OrderedDict(sorted(tree.items(), key=lambda i: sort_options(i, module_name)))
 
 
 def on_page_markdown(
@@ -64,6 +64,7 @@ def on_page_markdown(
     if not is_reference_page(page):
         return markdown
     src_path = Path(config.docs_dir) / page.file.src_path
+    module_name = src_path.parent.stem
     env = config.theme.get_env()
     env.filters["pygments"] = pygments
 
@@ -74,7 +75,7 @@ def on_page_markdown(
         log.error(f"{options_path} does not exist")
         return None
     with open(options_path, "r") as f:
-        options = preprocess_options(json.load(f))
+        options = preprocess_options(json.load(f), module_name)
     reference = env.get_template("reference_options.html").render(options=options)
 
     return "\n\n".join([header, markdown, reference])

From 2bf5e20f2300627a895f63b3e54473b4fc605cd1 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 10:46:46 +0200
Subject: [PATCH 40/67] docs: add note regarding upstream PR

for mkdocs-awesome-pages-plugin
---
 .../reference-website/mkdocs-awesome-pages-plugin.nix          | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix b/modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix
index f7bf1734..bd8e10e8 100644
--- a/modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix
+++ b/modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix
@@ -1,3 +1,6 @@
+# Can be removed from dream2nix repo when
+# https://github.com/NixOS/nixpkgs/pull/320709
+# is in nixpkgs-unstable
 {
   lib,
   buildPythonPackage,

From b6b9e5d2fb3bc4a348faebb07608525d217fb56b Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 12:55:38 +0200
Subject: [PATCH 41/67] docs: customize toc-item.html

to add collapsible subtrees
---
 docs/theme/partials/toc-item.html | 52 +++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 docs/theme/partials/toc-item.html

diff --git a/docs/theme/partials/toc-item.html b/docs/theme/partials/toc-item.html
new file mode 100644
index 00000000..34d3dfae
--- /dev/null
+++ b/docs/theme/partials/toc-item.html
@@ -0,0 +1,52 @@
+<!--
+     Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
+
+     Permission is hereby granted, free of charge, to any person obtaining a copy
+     of this software and associated documentation files (the "Software"), to
+     deal in the Software without restriction, including without limitation the
+     rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+     sell copies of the Software, and to permit persons to whom the Software is
+     furnished to do so, subject to the following conditions:
+
+     The above copyright notice and this permission notice shall be included in
+     all copies or substantial portions of the Software.
+
+     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+     IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+     FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+     AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+     IN THE SOFTWARE.
+-->
+
+<!-- Table of contents item -->
+<li class="md-nav__item">
+    {%- set should_collapse = toc_item.level > 2 and toc_item.children -%}
+    {% if should_collapse -%}
+    <details>
+        <summary>
+            {%- endif %}
+            <a href="{{ toc_item.url }}" class="md-nav__link">
+                <span class="md-ellipsis">
+                    {{ toc_item.title }}
+                </span>
+            </a>
+         {% if should_collapse -%}
+        </summary>
+        {%- endif %}
+
+        <!-- Table of contents list -->
+        {% if toc_item.children %}
+        <nav class="md-nav" aria-label="{{ toc_item.title | striptags }}">
+            <ul class="md-nav__list">
+                {% for toc_item in toc_item.children %}
+                {% include "partials/toc-item.html" %}
+                {% endfor %}
+            </ul>
+        </nav>
+        {% endif %}
+        {% if should_collapse -%}
+    </details>
+    {%- endif %}
+</li>

From eeb48666ca3c345b3357cd99302d058650886d88 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 12:58:02 +0200
Subject: [PATCH 42/67] docs: fix reference titles

---
 docs/theme/reference_options.html | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
index bcf91490..940f3158 100644
--- a/docs/theme/reference_options.html
+++ b/docs/theme/reference_options.html
@@ -1,7 +1,7 @@
 ## Options
 {%- for name, option in options.items() recursive %}
 
-##{{loop.depth * "#"}} {{ name.replace("<", "&lt;").replace(">", "&gt;") }}
+##{{loop.depth * "#"}} {{ ((option.loc | join (".")) or name).replace("<", "&lt;").replace(">", "&gt;") }}
 
 {{ option.description or '' }}
 
@@ -29,6 +29,7 @@
         </td>
     </tr>
     {%- endif -%}
+
 </table>
 {% endif %}
 {%- if option.children -%}

From 5f3051487a86206f0704476bb08756b965c563b7 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 13:01:19 +0200
Subject: [PATCH 43/67] docs: don't render full paths in reference toc

---
 docs/theme/partials/toc-item.html | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/theme/partials/toc-item.html b/docs/theme/partials/toc-item.html
index 34d3dfae..5af8905a 100644
--- a/docs/theme/partials/toc-item.html
+++ b/docs/theme/partials/toc-item.html
@@ -29,7 +29,11 @@
             {%- endif %}
             <a href="{{ toc_item.url }}" class="md-nav__link">
                 <span class="md-ellipsis">
+                    {%- if page.url.split("/")[-3] == "reference" -%}
+                    {{ toc_item.title.split(".")[-1] }}
+                    {%- else -%}
                     {{ toc_item.title }}
+                    {%- endif -%}
                 </span>
             </a>
          {% if should_collapse -%}

From c1d15024865a3f005933f602f3c14f0d23b6bb42 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 13:17:34 +0200
Subject: [PATCH 44/67] docs: improve options reference layout

---
 docs/src/style.css                | 4 ++++
 docs/theme/reference_options.html | 8 +++++---
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/src/style.css b/docs/src/style.css
index 4e3b12e6..d95edd65 100644
--- a/docs/src/style.css
+++ b/docs/src/style.css
@@ -6,3 +6,7 @@
 [data-md-component="toc"] .md-nav__link {
     display: inline-flex;
 }
+
+.md-typeset td pre {
+    margin: 0;
+}
diff --git a/docs/theme/reference_options.html b/docs/theme/reference_options.html
index 940f3158..9f863c35 100644
--- a/docs/theme/reference_options.html
+++ b/docs/theme/reference_options.html
@@ -3,13 +3,15 @@
 
 ##{{loop.depth * "#"}} {{ ((option.loc | join (".")) or name).replace("<", "&lt;").replace(">", "&gt;") }}
 
+{% if (option.description or '') != "This option has no description." -%}
 {{ option.description or '' }}
+{%- endif %}
 
 {% if "type" in option %}
 <table>
     <tr>
         <td>type</td>
-        <td><code>{{ option.type }}</code> {{ "(read only)" if option.readOnly else "" }}</td>
+        <td>{{ option.type}} {{ "(read only)" if option.readOnly else "" }}</td>
     </tr>
     <tr>
         <td>source</td>
@@ -18,14 +20,14 @@
     {%- if option.default -%}
     <tr>
         <td>default</td>
-        <td><pre>{{(option.default | default({})).text | pygments("nix")}}</pre></td>
+        <td>{{(option.default | default({})).text | pygments("nix")}}</td>
     </tr>
     {%- endif -%}
     {%- if option.example -%}
     <tr>
         <td>example</td>
         <td>
-            <pre>{{(option.example | default({})).text | pygments("nix")}}</pre>
+            {{(option.example | default({})).text | pygments("nix")}}
         </td>
     </tr>
     {%- endif -%}

From 233a797b5ccbd6d71e9cdff982da64e68b6e8c81 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 15:32:24 +0200
Subject: [PATCH 45/67] docs: put modules where state != "released"...

into a separate navigation section.
---
 docs/hooks/render_options.py | 43 +++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
index 76c189e4..7878dd9f 100644
--- a/docs/hooks/render_options.py
+++ b/docs/hooks/render_options.py
@@ -3,11 +3,13 @@ import json
 from pathlib import Path
 from collections import OrderedDict
 from typing import Dict, Tuple
+from urllib.request import UnknownHandler
 
 from mkdocs.structure.pages import Page
+from mkdocs.structure.nav import Navigation, Section
 from mkdocs.structure.files import Files
 from mkdocs.config.defaults import MkDocsConfig
-
+from mkdocs.plugins import event_priority
 
 from pygments import highlight
 from pygments.lexers import get_lexer_by_name
@@ -61,6 +63,13 @@ def preprocess_options(options, module_name):
 def on_page_markdown(
     markdown: str, page: Page, config: MkDocsConfig, files: Files
 ) -> str | None:
+    """Check whether the source path starts with "reference/".
+    If it does:
+    - render a header template, containing values from the source markdown file
+    - render the source markdown file
+    - render an options.json file containing nixos option definitions from the
+      same directory where the source file is found. Then render those options.
+    """
     if not is_reference_page(page):
         return markdown
     src_path = Path(config.docs_dir) / page.file.src_path
@@ -79,3 +88,35 @@ def on_page_markdown(
     reference = env.get_template("reference_options.html").render(options=options)
 
     return "\n\n".join([header, markdown, reference])
+
+
+@event_priority(-100)
+def on_nav(nav: Navigation, config: MkDocsConfig, files: Files) -> Navigation | None:
+    """Customize the navigation: If a reference section is found,
+    filter for a "state" variable defined in a markdown files front-matter.
+    Leave all items where "state" equals "released" as-is, but put
+    all others in an "experimental" section below that."""
+    try:
+        reference_section = next(filter(lambda i: i.title == "Reference", nav.items))
+        reference_index = nav.items.index(reference_section)
+    except StopIteration:
+        # Return the navigation as-is if we don't find
+        # a reference section
+        return nav
+
+    released = []
+    experimental = []
+    for page in reference_section.children:
+        # to have metadata from the yaml front-matter available
+        page.read_source(config)
+        state = page.meta.get("state")
+        if state == "released":
+            released.append(page)
+        else:
+            experimental.append(page)
+
+    experimental_section = Section("Experimental", experimental)
+    reference_section.children = released + [experimental_section]
+
+    nav.items[reference_index] = reference_section
+    return nav

From 9aae1937a458229ecda24c0026a09001f4c07f9e Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Tue, 18 Jun 2024 15:39:32 +0200
Subject: [PATCH 46/67] docs: Experimental -> Experimental Modules

---
 docs/hooks/render_options.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/hooks/render_options.py b/docs/hooks/render_options.py
index 7878dd9f..168f87be 100644
--- a/docs/hooks/render_options.py
+++ b/docs/hooks/render_options.py
@@ -115,7 +115,7 @@ def on_nav(nav: Navigation, config: MkDocsConfig, files: Files) -> Navigation |
         else:
             experimental.append(page)
 
-    experimental_section = Section("Experimental", experimental)
+    experimental_section = Section("Experimental Modules", experimental)
     reference_section.children = released + [experimental_section]
 
     nav.items[reference_index] = reference_section

From 4f1b50435693fb2ae03583d3a808cec9b2706bb7 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 18 Jun 2024 18:31:41 +0000
Subject: [PATCH 47/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/e913ae340076bbb73d9f4d3d065c2bca7caafb16?narHash=sha256-Ds1QpobBX2yoUDx9ZruqVGJ/uQPgcXoYuobBguyKEh8%3D' (2024-06-11)
  → 'github:NixOS/nixpkgs/38d3352a65ac9d621b0cd3074d3bef27199ff78f?narHash=sha256-pmjP5ePc1jz%2BOkona3HxD7AYT0wbrCwm9bXAlj08nDM%3D' (2024-06-17)
---
 flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flake.lock b/flake.lock
index 557a2d1c..b037f842 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1718149104,
-        "narHash": "sha256-Ds1QpobBX2yoUDx9ZruqVGJ/uQPgcXoYuobBguyKEh8=",
+        "lastModified": 1718606988,
+        "narHash": "sha256-pmjP5ePc1jz+Okona3HxD7AYT0wbrCwm9bXAlj08nDM=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "e913ae340076bbb73d9f4d3d065c2bca7caafb16",
+        "rev": "38d3352a65ac9d621b0cd3074d3bef27199ff78f",
         "type": "github"
       },
       "original": {

From c6915501f676f0f30c501f20b686a35072396ac3 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 18 Jun 2024 18:31:41 +0000
Subject: [PATCH 48/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/e913ae340076bbb73d9f4d3d065c2bca7caafb16?narHash=sha256-Ds1QpobBX2yoUDx9ZruqVGJ/uQPgcXoYuobBguyKEh8%3D' (2024-06-11)
  → 'github:NixOS/nixpkgs/38d3352a65ac9d621b0cd3074d3bef27199ff78f?narHash=sha256-pmjP5ePc1jz%2BOkona3HxD7AYT0wbrCwm9bXAlj08nDM%3D' (2024-06-17)
---
 dev-flake/flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/dev-flake/flake.lock b/dev-flake/flake.lock
index b74169da..80bcf9c7 100644
--- a/dev-flake/flake.lock
+++ b/dev-flake/flake.lock
@@ -145,11 +145,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1718149104,
-        "narHash": "sha256-Ds1QpobBX2yoUDx9ZruqVGJ/uQPgcXoYuobBguyKEh8=",
+        "lastModified": 1718606988,
+        "narHash": "sha256-pmjP5ePc1jz+Okona3HxD7AYT0wbrCwm9bXAlj08nDM=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "e913ae340076bbb73d9f4d3d065c2bca7caafb16",
+        "rev": "38d3352a65ac9d621b0cd3074d3bef27199ff78f",
         "type": "github"
       },
       "original": {

From ea0ef38c778f92227b682bf710c33b806714412e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 20 Jun 2024 18:31:00 +0000
Subject: [PATCH 49/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/38d3352a65ac9d621b0cd3074d3bef27199ff78f?narHash=sha256-pmjP5ePc1jz%2BOkona3HxD7AYT0wbrCwm9bXAlj08nDM%3D' (2024-06-17)
  → 'github:NixOS/nixpkgs/37a45fb6993f14555f50b18fbcf4945b82a35707?narHash=sha256-%2BH7PnuwEDDDxUMa3ItAcSRDK5%2BjfMJap/zHiuACyIfc%3D' (2024-06-18)
---
 flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flake.lock b/flake.lock
index b037f842..83d84f71 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1718606988,
-        "narHash": "sha256-pmjP5ePc1jz+Okona3HxD7AYT0wbrCwm9bXAlj08nDM=",
+        "lastModified": 1718742829,
+        "narHash": "sha256-+H7PnuwEDDDxUMa3ItAcSRDK5+jfMJap/zHiuACyIfc=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "38d3352a65ac9d621b0cd3074d3bef27199ff78f",
+        "rev": "37a45fb6993f14555f50b18fbcf4945b82a35707",
         "type": "github"
       },
       "original": {

From 5e523a4e419a31dedae61443b9f78397e64eeea9 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 20 Jun 2024 18:31:00 +0000
Subject: [PATCH 50/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/38d3352a65ac9d621b0cd3074d3bef27199ff78f?narHash=sha256-pmjP5ePc1jz%2BOkona3HxD7AYT0wbrCwm9bXAlj08nDM%3D' (2024-06-17)
  → 'github:NixOS/nixpkgs/37a45fb6993f14555f50b18fbcf4945b82a35707?narHash=sha256-%2BH7PnuwEDDDxUMa3ItAcSRDK5%2BjfMJap/zHiuACyIfc%3D' (2024-06-18)
---
 dev-flake/flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/dev-flake/flake.lock b/dev-flake/flake.lock
index 80bcf9c7..887bc0c5 100644
--- a/dev-flake/flake.lock
+++ b/dev-flake/flake.lock
@@ -145,11 +145,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1718606988,
-        "narHash": "sha256-pmjP5ePc1jz+Okona3HxD7AYT0wbrCwm9bXAlj08nDM=",
+        "lastModified": 1718742829,
+        "narHash": "sha256-+H7PnuwEDDDxUMa3ItAcSRDK5+jfMJap/zHiuACyIfc=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "38d3352a65ac9d621b0cd3074d3bef27199ff78f",
+        "rev": "37a45fb6993f14555f50b18fbcf4945b82a35707",
         "type": "github"
       },
       "original": {

From 6d786109563d1a74bebbe4ab6422d96010b8f598 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 21 Jun 2024 18:31:10 +0000
Subject: [PATCH 51/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/37a45fb6993f14555f50b18fbcf4945b82a35707?narHash=sha256-%2BH7PnuwEDDDxUMa3ItAcSRDK5%2BjfMJap/zHiuACyIfc%3D' (2024-06-18)
  → 'github:NixOS/nixpkgs/9b10b8f00cb5494795e5f51b39210fed4d2b0748?narHash=sha256-jab3Kpc8O1z3qxwVsCMHL4%2B18n5Wy/HHKyu1fcsF7gs%3D' (2024-06-20)
---
 flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flake.lock b/flake.lock
index 83d84f71..2f44d2c1 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1718742829,
-        "narHash": "sha256-+H7PnuwEDDDxUMa3ItAcSRDK5+jfMJap/zHiuACyIfc=",
+        "lastModified": 1718870667,
+        "narHash": "sha256-jab3Kpc8O1z3qxwVsCMHL4+18n5Wy/HHKyu1fcsF7gs=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "37a45fb6993f14555f50b18fbcf4945b82a35707",
+        "rev": "9b10b8f00cb5494795e5f51b39210fed4d2b0748",
         "type": "github"
       },
       "original": {

From ec375230a76fd6df5b5655f621268d2325278c0a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 21 Jun 2024 18:31:10 +0000
Subject: [PATCH 52/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/37a45fb6993f14555f50b18fbcf4945b82a35707?narHash=sha256-%2BH7PnuwEDDDxUMa3ItAcSRDK5%2BjfMJap/zHiuACyIfc%3D' (2024-06-18)
  → 'github:NixOS/nixpkgs/9b10b8f00cb5494795e5f51b39210fed4d2b0748?narHash=sha256-jab3Kpc8O1z3qxwVsCMHL4%2B18n5Wy/HHKyu1fcsF7gs%3D' (2024-06-20)
---
 dev-flake/flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/dev-flake/flake.lock b/dev-flake/flake.lock
index 887bc0c5..2b7d082c 100644
--- a/dev-flake/flake.lock
+++ b/dev-flake/flake.lock
@@ -145,11 +145,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1718742829,
-        "narHash": "sha256-+H7PnuwEDDDxUMa3ItAcSRDK5+jfMJap/zHiuACyIfc=",
+        "lastModified": 1718870667,
+        "narHash": "sha256-jab3Kpc8O1z3qxwVsCMHL4+18n5Wy/HHKyu1fcsF7gs=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "37a45fb6993f14555f50b18fbcf4945b82a35707",
+        "rev": "9b10b8f00cb5494795e5f51b39210fed4d2b0748",
         "type": "github"
       },
       "original": {

From 58bf45413a126b618b334400cd6d54a4ab0a8052 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Sat, 22 Jun 2024 18:29:33 +0000
Subject: [PATCH 53/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/9b10b8f00cb5494795e5f51b39210fed4d2b0748?narHash=sha256-jab3Kpc8O1z3qxwVsCMHL4%2B18n5Wy/HHKyu1fcsF7gs%3D' (2024-06-20)
  → 'github:NixOS/nixpkgs/90338afd6177fc683a04d934199d693708c85a3b?narHash=sha256-%2B1xgeIow4gJeiwo4ETvMRvWoircnvb0JOt7NS9kUhoM%3D' (2024-06-21)
---
 flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flake.lock b/flake.lock
index 2f44d2c1..aecdd47f 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1718870667,
-        "narHash": "sha256-jab3Kpc8O1z3qxwVsCMHL4+18n5Wy/HHKyu1fcsF7gs=",
+        "lastModified": 1718983919,
+        "narHash": "sha256-+1xgeIow4gJeiwo4ETvMRvWoircnvb0JOt7NS9kUhoM=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "9b10b8f00cb5494795e5f51b39210fed4d2b0748",
+        "rev": "90338afd6177fc683a04d934199d693708c85a3b",
         "type": "github"
       },
       "original": {

From 2b2cb862ad39f458ea6321c606ad235655149f71 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Sat, 22 Jun 2024 18:29:34 +0000
Subject: [PATCH 54/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/9b10b8f00cb5494795e5f51b39210fed4d2b0748?narHash=sha256-jab3Kpc8O1z3qxwVsCMHL4%2B18n5Wy/HHKyu1fcsF7gs%3D' (2024-06-20)
  → 'github:NixOS/nixpkgs/90338afd6177fc683a04d934199d693708c85a3b?narHash=sha256-%2B1xgeIow4gJeiwo4ETvMRvWoircnvb0JOt7NS9kUhoM%3D' (2024-06-21)
---
 dev-flake/flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/dev-flake/flake.lock b/dev-flake/flake.lock
index 2b7d082c..c6918853 100644
--- a/dev-flake/flake.lock
+++ b/dev-flake/flake.lock
@@ -145,11 +145,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1718870667,
-        "narHash": "sha256-jab3Kpc8O1z3qxwVsCMHL4+18n5Wy/HHKyu1fcsF7gs=",
+        "lastModified": 1718983919,
+        "narHash": "sha256-+1xgeIow4gJeiwo4ETvMRvWoircnvb0JOt7NS9kUhoM=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "9b10b8f00cb5494795e5f51b39210fed4d2b0748",
+        "rev": "90338afd6177fc683a04d934199d693708c85a3b",
         "type": "github"
       },
       "original": {

From fb55ba188252fca66cfb9185a327829872f6f15d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Sun, 23 Jun 2024 18:29:12 +0000
Subject: [PATCH 55/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/90338afd6177fc683a04d934199d693708c85a3b?narHash=sha256-%2B1xgeIow4gJeiwo4ETvMRvWoircnvb0JOt7NS9kUhoM%3D' (2024-06-21)
  → 'github:NixOS/nixpkgs/9693852a2070b398ee123a329e68f0dab5526681?narHash=sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs%3D' (2024-06-22)
---
 flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flake.lock b/flake.lock
index aecdd47f..4277e18e 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1718983919,
-        "narHash": "sha256-+1xgeIow4gJeiwo4ETvMRvWoircnvb0JOt7NS9kUhoM=",
+        "lastModified": 1719082008,
+        "narHash": "sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "90338afd6177fc683a04d934199d693708c85a3b",
+        "rev": "9693852a2070b398ee123a329e68f0dab5526681",
         "type": "github"
       },
       "original": {

From c46b53791ca39d824e0d839209b8b1981fa295c0 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Sun, 23 Jun 2024 18:29:13 +0000
Subject: [PATCH 56/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/90338afd6177fc683a04d934199d693708c85a3b?narHash=sha256-%2B1xgeIow4gJeiwo4ETvMRvWoircnvb0JOt7NS9kUhoM%3D' (2024-06-21)
  → 'github:NixOS/nixpkgs/9693852a2070b398ee123a329e68f0dab5526681?narHash=sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs%3D' (2024-06-22)
---
 dev-flake/flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/dev-flake/flake.lock b/dev-flake/flake.lock
index c6918853..22250933 100644
--- a/dev-flake/flake.lock
+++ b/dev-flake/flake.lock
@@ -145,11 +145,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1718983919,
-        "narHash": "sha256-+1xgeIow4gJeiwo4ETvMRvWoircnvb0JOt7NS9kUhoM=",
+        "lastModified": 1719082008,
+        "narHash": "sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "90338afd6177fc683a04d934199d693708c85a3b",
+        "rev": "9693852a2070b398ee123a329e68f0dab5526681",
         "type": "github"
       },
       "original": {

From e1ea06ffd34c254745a0585e58ac47ce3c2447af Mon Sep 17 00:00:00 2001
From: purepani <pani0028@umn.edu>
Date: Sun, 23 Jun 2024 15:20:11 -0500
Subject: [PATCH 57/67] python: Moves python-local-development example into src
 layout

---
 .../python-local-development/{ => src}/mytool/__init__.py         | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename examples/packages/languages/python-local-development/{ => src}/mytool/__init__.py (100%)

diff --git a/examples/packages/languages/python-local-development/mytool/__init__.py b/examples/packages/languages/python-local-development/src/mytool/__init__.py
similarity index 100%
rename from examples/packages/languages/python-local-development/mytool/__init__.py
rename to examples/packages/languages/python-local-development/src/mytool/__init__.py

From cbe72c89ba649b6ba9aad7b123076f45e0efc3ce Mon Sep 17 00:00:00 2001
From: purepani <pani0028@umn.edu>
Date: Sun, 23 Jun 2024 15:20:56 -0500
Subject: [PATCH 58/67] python-editables: Exports environment variables for
 python whether .dream2nix needs updating or not (editables.py)

---
 .../dream2nix/python-editables/editable.py    | 30 +++++++++++--------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/modules/dream2nix/python-editables/editable.py b/modules/dream2nix/python-editables/editable.py
index efd8516b..d18c87c1 100644
--- a/modules/dream2nix/python-editables/editable.py
+++ b/modules/dream2nix/python-editables/editable.py
@@ -1,14 +1,14 @@
-import os
-import sys
-import json
-import shutil
-import subprocess
 import configparser
 import importlib
+import json
+import os
+import shutil
+import subprocess
+import sys
 from contextlib import redirect_stdout
-from textwrap import dedent
 from pathlib import Path
 from tempfile import TemporaryDirectory
+from textwrap import dedent
 
 import tomli
 
@@ -173,6 +173,15 @@ def needs_update(args, dream2nix_python_dir):
     return old_args != args
 
 
+def export_environment_vars(python_environment, bin_dir, site_dir, site_packages):
+    print(
+        f"""
+    export PYTHONPATH="{site_dir}:{python_environment / site_packages}:$PYTHONPATH"
+    export PATH="{bin_dir}:${python_environment}/bin:$PATH"
+        """
+    )
+
+
 def pretty_print_editables(editables, root_dir, root_name):
     if os.environ.get("D2N_QUIET"):
         return
@@ -218,6 +227,7 @@ if __name__ == "__main__":
         if dream2nix_python_dir.exists():
             shutil.rmtree(dream2nix_python_dir)
     else:
+        export_environment_vars(python_environment, bin_dir, site_dir, site_packages)
         pretty_print_editables(editables, root_dir, root_name)
         exit(0)
 
@@ -259,14 +269,8 @@ for index, path in enumerate(sys.path):
         """
         )
 
-    print(
-        f"""
-export PYTHONPATH="{site_dir}:{python_environment / site_packages}:$PYTHONPATH"
-export PATH="{bin_dir}:${python_environment}/bin:$PATH"
-    """
-    )
-
     with open(dream2nix_python_dir / "editable-args.json", "w") as f:
         json.dump(args, f, indent=2)
 
+    export_environment_vars(python_environment, bin_dir, site_dir, site_packages)
     pretty_print_editables(editables, root_dir, root_name)

From 3288c5cf4448ed843455a65737b4f27d42828555 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 25 Jun 2024 18:31:49 +0000
Subject: [PATCH 59/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/9693852a2070b398ee123a329e68f0dab5526681?narHash=sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs%3D' (2024-06-22)
  → 'github:NixOS/nixpkgs/cfb89a95f19bea461fc37228dc4d07b22fe617c2?narHash=sha256-kOUKtKfYEh8h8goL/P6lKF4Jb0sXnEkFyEganzdTGvo%3D' (2024-06-25)
---
 flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flake.lock b/flake.lock
index 4277e18e..159c0fe9 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1719082008,
-        "narHash": "sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs=",
+        "lastModified": 1719285171,
+        "narHash": "sha256-kOUKtKfYEh8h8goL/P6lKF4Jb0sXnEkFyEganzdTGvo=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "9693852a2070b398ee123a329e68f0dab5526681",
+        "rev": "cfb89a95f19bea461fc37228dc4d07b22fe617c2",
         "type": "github"
       },
       "original": {

From aa983fd908a0d7e235a8c8a77b803231b9ff2e4a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 25 Jun 2024 18:31:49 +0000
Subject: [PATCH 60/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/9693852a2070b398ee123a329e68f0dab5526681?narHash=sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs%3D' (2024-06-22)
  → 'github:NixOS/nixpkgs/cfb89a95f19bea461fc37228dc4d07b22fe617c2?narHash=sha256-kOUKtKfYEh8h8goL/P6lKF4Jb0sXnEkFyEganzdTGvo%3D' (2024-06-25)
---
 dev-flake/flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/dev-flake/flake.lock b/dev-flake/flake.lock
index 22250933..f1824b94 100644
--- a/dev-flake/flake.lock
+++ b/dev-flake/flake.lock
@@ -145,11 +145,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1719082008,
-        "narHash": "sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs=",
+        "lastModified": 1719285171,
+        "narHash": "sha256-kOUKtKfYEh8h8goL/P6lKF4Jb0sXnEkFyEganzdTGvo=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "9693852a2070b398ee123a329e68f0dab5526681",
+        "rev": "cfb89a95f19bea461fc37228dc4d07b22fe617c2",
         "type": "github"
       },
       "original": {

From 00ccd3da762a17a4c57263a50de7a5623d791298 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Mon, 24 Jun 2024 12:47:15 +0200
Subject: [PATCH 61/67] docs/pip: Add intro to README

---
 modules/dream2nix/pip/README.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/modules/dream2nix/pip/README.md b/modules/dream2nix/pip/README.md
index d5f05f5b..d6f43498 100644
--- a/modules/dream2nix/pip/README.md
+++ b/modules/dream2nix/pip/README.md
@@ -5,4 +5,26 @@ maintainers:
   - phaer
 ---
 
-Python packaging via [pip](https://pip.pypa.io/).
+A module to package python projects via [pip](https://pip.pypa.io/).
+
+Under the hood, it uses [./pkgs/fetchPipMetadata](https://github.com/nix-community/dream2nix/tree/main/pkgs/fetchPipMetadata) to
+run `pip install --dry-run --report [...]` with reproducible inputs and converts the resulting installation report into a dream2nix
+lock file.
+
+!!! note
+
+    Due to limitations in `pip`s cross-platform support, the resulting
+    lock-files are platform-specific!
+    We therefore recommend setting `paths.lockFile` to `lock.${system}.json`
+    for all projects where you use the pip module.
+
+    Check out the [pdm module](../WIP-python-pdm/index.md) if you need a solution that
+    allows locking for multiple platforms at once!
+
+During building, it uses this lock file to build each dependency as well as the top-level package in separate derivations
+while allowing overrides and further customization via [dream2nix module system](../../modules.md).
+
+## Getting started
+
+See [Build a python project with pip](../../guides/pip.md).
+

From 35e13f912ad3e9a7d461e519f7a7a8576fecc794 Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Mon, 24 Jun 2024 12:47:27 +0200
Subject: [PATCH 62/67] docs/buildPythonPackage: reformat

---
 .../dream2nix/buildPythonPackage/interface.nix   | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/modules/dream2nix/buildPythonPackage/interface.nix b/modules/dream2nix/buildPythonPackage/interface.nix
index ef2d4dd7..37019eab 100644
--- a/modules/dream2nix/buildPythonPackage/interface.nix
+++ b/modules/dream2nix/buildPythonPackage/interface.nix
@@ -93,13 +93,15 @@ in {
       description = ''
         Whether the pyproject format should be used. When set to `true`,
         `pypaBuildHook` will be used, and you can add the required build dependencies
-        from `build-system.requires` to `build-system`. Note that the pyproject
-        format falls back to using `setuptools`, so you can use `pyproject = true`
-        even if the package only has a `setup.py`. When set to `false`, you can
-        use the existing hooks or provide your own logic to build the
-        package. This can be useful for packages that don't support the pyproject
-        format. When unset, the legacy `setuptools` hooks are used for backwards
-        compatibility.
+        from `build-system.requires` to `build-system`.
+
+        Note that the pyproject format falls back to using `setuptools`, so
+        you can use `pyproject = true` even if the package only has a `setup.py`.
+        When set to `false`, you can use the existing hooks or provide your own
+        logic to build the package. This can be useful for packages that don't
+        support the pyproject format.
+
+        When unset, the legacy `setuptools` hooks are used for backwards compatibility.
       '';
     };
 

From 3f1417738823c90c4b4600a3f2f3fb59e773b6dd Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Mon, 24 Jun 2024 14:17:49 +0200
Subject: [PATCH 63/67] examples/hello: 2.12 -> 2.12.1

---
 examples/repo-with-packages/packages/hello/default.nix | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/repo-with-packages/packages/hello/default.nix b/examples/repo-with-packages/packages/hello/default.nix
index 59c3853d..668a1af3 100644
--- a/examples/repo-with-packages/packages/hello/default.nix
+++ b/examples/repo-with-packages/packages/hello/default.nix
@@ -9,7 +9,7 @@
   ];
 
   name = "hello";
-  version = "2.12";
+  version = "2.12.1";
 
   deps = {nixpkgs, ...}: {
     inherit
@@ -21,7 +21,7 @@
   mkDerivation = {
     src = builtins.fetchTarball {
       url = "https://ftp.gnu.org/gnu/hello/hello-${config.version}.tar.gz";
-      sha256 = "sha256-4GQeKLIxoWfYiOraJub5RsHNVQBr2H+3bfPP22PegdU=";
+      sha256 = "0xw6cr5jgi1ir13q6apvrivwmmpr5j8vbymp0x6ll0kcv6366hnn";
     };
   };
 }

From 68e0c76cb5114ee8cc5f9a21911a06031efe15ec Mon Sep 17 00:00:00 2001
From: phaer <hello@phaer.org>
Date: Mon, 24 Jun 2024 15:01:47 +0200
Subject: [PATCH 64/67] docs: enable copy button for code blocks

---
 docs/mkdocs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index e0b0ec09..4db23ffa 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -52,6 +52,7 @@ theme:
     - navigation.path
     - navigation.top
     - toc.follow
+    - content.code.copy
     - content.code.annotate
 
 extra:

From 5253c929b7519a954d18c80871d30ac4c215a32d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 26 Jun 2024 18:30:56 +0000
Subject: [PATCH 65/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/cfb89a95f19bea461fc37228dc4d07b22fe617c2?narHash=sha256-kOUKtKfYEh8h8goL/P6lKF4Jb0sXnEkFyEganzdTGvo%3D' (2024-06-25)
  → 'github:NixOS/nixpkgs/9c513fc6fb75142f6aec6b7545cb8af2236b80f5?narHash=sha256-bu0xbu2Z6DDzA9LGV81yJunIti6r7tjUImeR8orAL/I%3D' (2024-06-25)
---
 flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flake.lock b/flake.lock
index 159c0fe9..c6a502de 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1719285171,
-        "narHash": "sha256-kOUKtKfYEh8h8goL/P6lKF4Jb0sXnEkFyEganzdTGvo=",
+        "lastModified": 1719317636,
+        "narHash": "sha256-bu0xbu2Z6DDzA9LGV81yJunIti6r7tjUImeR8orAL/I=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "cfb89a95f19bea461fc37228dc4d07b22fe617c2",
+        "rev": "9c513fc6fb75142f6aec6b7545cb8af2236b80f5",
         "type": "github"
       },
       "original": {

From 481cd64f9674f60d99cb7a679b0d7f76358e18f4 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 26 Jun 2024 18:30:57 +0000
Subject: [PATCH 66/67] flake.lock: Update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/cfb89a95f19bea461fc37228dc4d07b22fe617c2?narHash=sha256-kOUKtKfYEh8h8goL/P6lKF4Jb0sXnEkFyEganzdTGvo%3D' (2024-06-25)
  → 'github:NixOS/nixpkgs/9c513fc6fb75142f6aec6b7545cb8af2236b80f5?narHash=sha256-bu0xbu2Z6DDzA9LGV81yJunIti6r7tjUImeR8orAL/I%3D' (2024-06-25)
---
 dev-flake/flake.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/dev-flake/flake.lock b/dev-flake/flake.lock
index f1824b94..5a3643e8 100644
--- a/dev-flake/flake.lock
+++ b/dev-flake/flake.lock
@@ -145,11 +145,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1719285171,
-        "narHash": "sha256-kOUKtKfYEh8h8goL/P6lKF4Jb0sXnEkFyEganzdTGvo=",
+        "lastModified": 1719317636,
+        "narHash": "sha256-bu0xbu2Z6DDzA9LGV81yJunIti6r7tjUImeR8orAL/I=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "cfb89a95f19bea461fc37228dc4d07b22fe617c2",
+        "rev": "9c513fc6fb75142f6aec6b7545cb8af2236b80f5",
         "type": "github"
       },
       "original": {

From ef046832220655543b105949787a9d0e6a24211e Mon Sep 17 00:00:00 2001
From: DavHau <hsngrmpf+github@gmail.com>
Date: Thu, 27 Jun 2024 15:21:24 +0700
Subject: [PATCH 67/67] fix: nix flake show requiring IFD

---
 .../nodejs-packaging-devshell-only/default.nix         | 10 +++++-----
 .../packages/languages/nodejs-packaging/default.nix    | 10 +++++-----
 .../packages/nodejs-packaging-package-lock/default.nix | 10 +++++-----
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/examples/packages/languages/nodejs-packaging-devshell-only/default.nix b/examples/packages/languages/nodejs-packaging-devshell-only/default.nix
index e34ee3ab..bd22c504 100644
--- a/examples/packages/languages/nodejs-packaging-devshell-only/default.nix
+++ b/examples/packages/languages/nodejs-packaging-devshell-only/default.nix
@@ -22,11 +22,11 @@
   version = "1.5.0";
 
   mkDerivation = {
-    src = config.deps.fetchFromGitHub {
-      owner = "DavHau";
-      repo = "cowsay";
-      rev = "package-lock-v3";
-      sha256 = "sha256-KuZkGWl5An78IFR5uT/2jVTXdm71oWB+p143svYVkqQ=";
+    src = builtins.fetchGit {
+      shallow = true;
+      url = "https://github.com/DavHau/cowsay";
+      ref = "package-lock-v3";
+      rev = "c89952cb75e3e54b8ca0033bd3499297610083c7";
     };
     # allow devshell to be built -> CI pipeline happy
     buildPhase = "mkdir $out";
diff --git a/examples/packages/languages/nodejs-packaging/default.nix b/examples/packages/languages/nodejs-packaging/default.nix
index 50e8c463..a5384d2a 100644
--- a/examples/packages/languages/nodejs-packaging/default.nix
+++ b/examples/packages/languages/nodejs-packaging/default.nix
@@ -10,11 +10,11 @@
   ];
 
   mkDerivation = {
-    src = config.deps.fetchFromGitHub {
-      owner = "DavHau";
-      repo = "cowsay";
-      rev = "package-lock-v3";
-      sha256 = "sha256-KuZkGWl5An78IFR5uT/2jVTXdm71oWB+p143svYVkqQ=";
+    src = builtins.fetchGit {
+      shallow = true;
+      url = "https://github.com/DavHau/cowsay";
+      ref = "package-lock-v3";
+      rev = "c89952cb75e3e54b8ca0033bd3499297610083c7";
     };
   };
 
diff --git a/modules/dream2nix/WIP-nodejs-builder-v3/tests/packages/nodejs-packaging-package-lock/default.nix b/modules/dream2nix/WIP-nodejs-builder-v3/tests/packages/nodejs-packaging-package-lock/default.nix
index ac35de34..735ee365 100644
--- a/modules/dream2nix/WIP-nodejs-builder-v3/tests/packages/nodejs-packaging-package-lock/default.nix
+++ b/modules/dream2nix/WIP-nodejs-builder-v3/tests/packages/nodejs-packaging-package-lock/default.nix
@@ -9,11 +9,11 @@
   ];
 
   mkDerivation = {
-    src = config.deps.fetchFromGitHub {
-      owner = "DavHau";
-      repo = "cowsay";
-      rev = "package-lock-v3";
-      sha256 = "sha256-KuZkGWl5An78IFR5uT/2jVTXdm71oWB+p143svYVkqQ=";
+    src = builtins.fetchGit {
+      shallow = true;
+      url = "https://github.com/DavHau/cowsay";
+      ref = "package-lock-v3";
+      rev = "c89952cb75e3e54b8ca0033bd3499297610083c7";
     };
   };