add check references

Author: aforemny

flake.nix

@@ -48,11 +48,17 @@
 
           templates = {
             default = {
-              path = ./template;
+              path = ./template/default;
               description = ''
                 A minimal flake using mkdocs-flake.
               '';
             };
+            references = {
+              path = ./template/references;
+              description = ''
+                TODO
+              '';
+            };
           };
         };
 
@@ -220,6 +226,39 @@
             checks = config.packages // {
               devShell = config.packages.default;
               formatting = treefmtEval.config.build.check inputs.self;
+              references =
+                let
+                  inherit ((builtins.getFlake "path:${toString ./.}?dir=template/references").packages.x86_64-linux)
+                    documentation
+                    ;
+                in
+                pkgs.runCommand "references" { } ''
+                  cd ${documentation}
+
+                  expectedOutput='NixOS module: foo
+                  I am a NixOS module.
+                  Feature 1
+                  I am feature 1 of NixOS module foo.
+                  (lib.mkIf (config ? "something") {
+                    foo = "bar";
+                  })
+
+                  Feature 2
+                  I am feature 2 of NixOS module foo.
+                  {
+                    baz = "bang";
+                    quux = lib.mkDefault null; # this should not render
+                  }'
+                  output=$(
+                    <${documentation}/references/modules-nixos/foo/index.html \
+                    ${lib.getExe pkgs.htmlq} --text --ignore-whitespace 'div[role=main]'
+                  )
+                  ${lib.getExe' pkgs.diffutils "diff"} --unified \
+                    <(echo "$expectedOutput") \
+                    <(echo "$output")
+
+                  touch $out
+                '';
             };
           };
       }

mkdocs/pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
     "mkdocs-swagger-ui-tag>=0.6.11",
     "pillow>=11.1.0",
     "plantuml-markdown>=3.11.1",
+    "properdocs-theme-mkdocs>=1.6.7",
 ]
 
 [tool.uv]

mkdocs/uv.lock

@@ -14,7 +14,7 @@ let
   strict = lib.optionalString cfg.strict "--strict";
 
   yaml = pkgs.formats.yaml { };
-  abs_docs_dir = cfg.mkdocs-root;
+  abs_docs_dir = "${flakeSelf.outPath}/${rel_docs_dir}";
   rel_docs_dir = lib.path.removePrefix (
     /. + (builtins.unsafeDiscardStringContext flakeSelf.outPath)
   ) cfg.mkdocs-root;
@@ -91,7 +91,7 @@ in
         # the hook allows the user to prepopulate font files to help avoid mkdocs
         # connecting to the internet.
         packages.documentation = pkgs.runCommand "mkdocs-flake-documentation" { } ''
-          cd ${cfg.mkdocs-root}
+          cd ${abs_docs_dir}
           mkdocs_args=(
             --site-dir $out
             ${strict}

modules/documentation.nix

@@ -0,0 +1,3 @@
+# references
+
+[./modules-nixos/foo](./modules-nixos/foo)