Merge pull request #65 from hercules-ci/markdown

Change docs to markdown and improve a bit

dev/default.nix

@@ -4,6 +4,7 @@ let
   self = {
     inherit (flake) inputs;
     outPath = ../.; # used by pre-commit module, etc
+    outputs = self.config.flake;
   } //
   fmc-lib.evalFlakeModule
     { inherit self; }

dev/flake-module.nix

@@ -30,25 +30,20 @@
     };
 
   };
-  flake = {
+  herculesCI = herculesCI@{ config, ... }: {
-    # Because of ./README.md, we can't use the built-in flake support, including
+    onPush.default.outputs = {
-    # the `effects` flake attribute. We have to define `herculesCI` ourselves.
+      effects =
-    options.herculesCI = lib.mkOption { type = lib.types.raw; };
+        withSystem "x86_64-linux" ({ config, pkgs, hci-effects, ... }: {
-    config.herculesCI = { branch, ... }: {
+          netlifyDeploy = hci-effects.netlifyDeploy {
-      onPush.default.outputs = {
+            content = config.packages.siteContent;
-        inherit (config.flake) packages checks;
+            secretName = "default-netlify";
-        effects =
+            siteId = "29a153b1-3698-433c-bc73-62415efb8117";
-          withSystem "x86_64-linux" ({ config, pkgs, effects, ... }: {
+            productionDeployment = herculesCI.config.repo.branch == "main";
-            netlifyDeploy = effects.netlifyDeploy {
+          };
-              content = config.packages.siteContent;
+        });
-              secretName = "default-netlify";
-              siteId = "29a153b1-3698-433c-bc73-62415efb8117";
-              productionDeployment = branch == "main";
-            };
-          });
-      };
     };
-
+  };
+  flake = {
     # for repl exploration / debug
     config.config = config;
     options.mySystem = lib.mkOption { default = config.allSystems.${builtins.currentSystem}; };

dev/flake.lock

@@ -1,5 +1,44 @@
 {
   "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1666885127,
+        "narHash": "sha256-uXA/3lhLhwOTBMn9a5zJODKqaRT+SuL5cpEmOz2ULoo=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "0e101dbae756d35a376a5e1faea532608e4a4b9a",
+        "type": "github"
+      },
+      "original": {
+        "id": "flake-parts",
+        "type": "indirect"
+      }
+    },
+    "flake-parts_2": {
+      "inputs": {
+        "nixpkgs": [
+          "hercules-ci-effects",
+          "hercules-ci-agent",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1657102481,
+        "narHash": "sha256-62Fuw8JgPub38OdgNefkIKOodM9nC3M0AG6lS+7smf4=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "608ed3502263d6f4f886d75c48fc2b444a4ab8d8",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "locked": {
         "lastModified": 1619345332,
@@ -15,16 +54,54 @@
         "type": "github"
       }
     },
-    "hercules-ci-effects": {
+    "flake-utils_2": {
+      "locked": {
+        "lastModified": 1667077288,
+        "narHash": "sha256-bdC8sFNDpT0HK74u9fUkpbf1MEzVYJ+ka7NXCdgBoaA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "6ee9ebb6b1ee695d2cacc4faa053a7b9baa76817",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "hercules-ci-agent": {
       "inputs": {
-        "nixpkgs": "nixpkgs"
+        "flake-parts": "flake-parts_2",
+        "nix-darwin": "nix-darwin",
+        "nixpkgs": "nixpkgs",
+        "pre-commit-hooks-nix": "pre-commit-hooks-nix"
       },
       "locked": {
-        "lastModified": 1653841712,
+        "lastModified": 1668032598,
-        "narHash": "sha256-XBF4i1MuIRAEbFpj3Z3fVaYxzNEsYapyENtw3vG+q1I=",
+        "narHash": "sha256-KJF0ULd33lLOQVO26Ea1NKObSi9DIUfaxXducaKKpec=",
+        "owner": "hercules-ci",
+        "repo": "hercules-ci-agent",
+        "rev": "58954ab190bbc27a9d5149ebdafbf80851476461",
+        "type": "github"
+      },
+      "original": {
+        "id": "hercules-ci-agent",
+        "ref": "on-schedule",
+        "type": "indirect"
+      }
+    },
+    "hercules-ci-effects": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "hercules-ci-agent": "hercules-ci-agent",
+        "nixpkgs": "nixpkgs_2"
+      },
+      "locked": {
+        "lastModified": 1668147980,
+        "narHash": "sha256-dHu5VIGQvZoHtqr5tmndpiVVk5JnJ/6wZUNRwEfvIxk=",
         "owner": "hercules-ci",
         "repo": "hercules-ci-effects",
-        "rev": "e14d2131b7c81acca3904b584ac45fb72da64dd2",
+        "rev": "244595b8dcfea8c6ac52a99157653162d26ea6d3",
         "type": "github"
       },
       "original": {
@@ -33,13 +110,35 @@
         "type": "github"
       }
     },
+    "nix-darwin": {
+      "inputs": {
+        "nixpkgs": [
+          "hercules-ci-effects",
+          "hercules-ci-agent",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1657835815,
+        "narHash": "sha256-CnZszAYpNKydh6N7+xg+eRtWNVoAAGqc6bg+Lpgq1xc=",
+        "owner": "LnL7",
+        "repo": "nix-darwin",
+        "rev": "54a24f042f93c79f5679f133faddedec61955cf2",
+        "type": "github"
+      },
+      "original": {
+        "owner": "LnL7",
+        "repo": "nix-darwin",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1647297614,
+        "lastModified": 1660305968,
-        "narHash": "sha256-ulGq3W5XsrBMU/u5k9d4oPy65pQTkunR4HKKtTq0RwY=",
+        "narHash": "sha256-r0X1pZCSEA6mzt5OuTA7nHuLmvnbkwgpFAh1iLIx4GU=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "73ad5f9e147c0d2a2061f1d4bd91e05078dc0b58",
+        "rev": "c4a0efdd5a728e20791b8d8d2f26f90ac228ee8d",
         "type": "github"
       },
       "original": {
@@ -49,18 +148,51 @@
         "type": "github"
       }
     },
+    "nixpkgs-lib": {
+      "locked": {
+        "dir": "lib",
+        "lastModified": 1665349835,
+        "narHash": "sha256-UK4urM3iN80UXQ7EaOappDzcisYIuEURFRoGQ/yPkug=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "34c5293a71ffdb2fe054eb5288adc1882c1eb0b1",
+        "type": "github"
+      },
+      "original": {
+        "dir": "lib",
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1653476104,
+        "lastModified": 1664384182,
-        "narHash": "sha256-oVuWUnGQX+fRn/cFoNfbLEUGtsyyXuMLDQFEZ2OxP3k=",
+        "narHash": "sha256-RM7C+6c9oSeZuoCCXOCRZUI1o4wpLo6pmOz1PxMN1ig=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "52392d42c156db5b889db7f3cc3e9909e4259b2a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_3": {
+      "locked": {
+        "lastModified": 1668145650,
+        "narHash": "sha256-RJsYVz7j6HhXQtcFQJz9bZsgwFG8MblmOt8A4iD1AlY=",
         "owner": "hercules-ci",
         "repo": "nixpkgs",
-        "rev": "612e22e67eb6f8d5bfb6288abe515e9da3b96103",
+        "rev": "b106ff14ede4034f8771025f8ac785144358f3cd",
         "type": "github"
       },
       "original": {
         "owner": "hercules-ci",
-        "ref": "module-docs-update",
+        "ref": "options-markdown-and-errors",
         "repo": "nixpkgs",
         "type": "github"
       }
@@ -69,6 +201,8 @@
       "inputs": {
         "flake-utils": "flake-utils",
         "nixpkgs": [
+          "hercules-ci-effects",
+          "hercules-ci-agent",
           "nixpkgs"
         ]
       },
@@ -87,11 +221,32 @@
         "type": "github"
       }
     },
+    "pre-commit-hooks-nix_2": {
+      "inputs": {
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1667992213,
+        "narHash": "sha256-8Ens8ozllvlaFMCZBxg6S7oUyynYx2v7yleC5M0jJsE=",
+        "owner": "cachix",
+        "repo": "pre-commit-hooks.nix",
+        "rev": "ebcbfe09d2bd6d15f68de3a0ebb1e4dcb5cd324b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "pre-commit-hooks.nix",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "hercules-ci-effects": "hercules-ci-effects",
-        "nixpkgs": "nixpkgs_2",
+        "nixpkgs": "nixpkgs_3",
-        "pre-commit-hooks-nix": "pre-commit-hooks-nix"
+        "pre-commit-hooks-nix": "pre-commit-hooks-nix_2"
       }
     }
   },

dev/flake.nix

@@ -3,13 +3,12 @@
 
   inputs = {
     # Flakes don't give us a good way to depend on .., so we don't.
-    # This has drastic consequences of course.
+    # As a consequence, this flake is a little non-standard, and
+    # we can't use the `nix` CLI as expected.
 
-    # https://github.com/NixOS/nixpkgs/pull/174460
+    nixpkgs.url = "github:hercules-ci/nixpkgs/options-markdown-and-errors";
-    # https://github.com/NixOS/nixpkgs/pull/174470
-    nixpkgs.url = "github:hercules-ci/nixpkgs/module-docs-update";
 
-    pre-commit-hooks-nix.url = "github:hercules-ci/pre-commit-hooks.nix/flakeModule";
+    pre-commit-hooks-nix.url = "github:cachix/pre-commit-hooks.nix";
     pre-commit-hooks-nix.inputs.nixpkgs.follows = "nixpkgs";
 
     hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";
@@ -17,7 +16,7 @@
 
   outputs = { self, ... }:
     {
-      # Without good or dev outputs, we only use flakes for inputs here.
       # The dev tooling is in ./flake-module.nix
+      # See comment at `inputs` above.
     };
 }

lib.nix

@@ -109,7 +109,7 @@ let
           ${name} = mkOption {
             type = types.lazyAttrsOf option.type;
             default = { };
-            description = lib.mdDoc ''
+            description = ''
               See {option}`perSystem.${name}` for description and examples.
             '';
           };

modules/apps.nix

@@ -28,13 +28,13 @@ let
         type = lib.types.enum [ "app" ];
         default = "app";
         description = ''
-          A type tag for <literal>apps</literal> consumers.
+          A type tag for `apps` consumers.
         '';
       };
       program = mkOption {
         type = programType;
         description = ''
-          A path to an executable or a derivation with <literal>meta.mainProgram</literal>.
+          A path to an executable or a derivation with `meta.mainProgram`.
         '';
       };
     };
@@ -46,7 +46,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf appType;
     default = { };
     description = ''
-      Programs runnable with nix run <literal>.#&lt;name></literal>.
+      Programs runnable with nix run `<name>`.
     '';
     example = lib.literalExpression or lib.literalExample ''
       {

modules/checks.nix

@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      Derivations to be built by nix flake check.
+      Derivations to be built by [`nix flake check`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake-check.html).
     '';
   };
   file = ./checks.nix;

modules/darwinModules.nix

@@ -19,7 +19,7 @@ in
         default = { };
         apply = mapAttrs (k: v: { _file = "${toString self.outPath}/flake.nix#darwinModules.${k}"; imports = [ v ]; });
         description = ''
-          Nix-darwin modules.
+          [nix-darwin](https://daiderd.com/nix-darwin/) modules.
         '';
       };
     };

modules/devShells.nix

@@ -14,8 +14,8 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      An attribute set of packages to be built by <literal>nix develop .#&lt;name></literal>.
+      An attribute set of packages to be used as shells.
-      <literal>nix build .#&lt;name></literal> will run <literal>devShells.&lt;name></literal>.
+      [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
     '';
   };
   file = ./devShells.nix;

modules/flake.nix

@@ -17,7 +17,7 @@ in
         ];
       };
       description = ''
-        Raw flake attributes. Any attribute can be set here, but some
+        Raw flake output attributes. Any attribute can be set here, but some
         attributes are represented by options, to provide appropriate
         configuration merging.
       '';

modules/formatter.nix

@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.nullOr types.package;
     default = null;
     description = ''
-      A package used by <literal>nix fmt</literal>.
+      A package used by [`nix fmt`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-fmt.html).
     '';
   };
   file = ./formatter.nix;

modules/legacyPackages.nix

@@ -14,7 +14,7 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.raw;
     default = { };
     description = ''
-      An attribute set of unmergeable values. This is also used by <literal>nix build .#&lt;attrpath></literal>.
+      An attribute set of unmergeable values. This is also used by [`nix build .#<attrpath>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
     '';
   };
   file = ./legacyPackages.nix;

modules/nixosConfigurations.nix

@@ -16,7 +16,7 @@ in
         type = types.lazyAttrsOf types.raw;
         default = { };
         description = ''
-          Instantiated NixOS configurations.
+          Instantiated NixOS configurations. Used by `nixos-rebuild`.
         '';
         example = literalExpression ''
           {
@@ -24,6 +24,7 @@ in
               system = "x86_64-linux";
               modules = [
                 ./my-machine/nixos-configuration.nix
+                config.nixosModules.my-module
               ];
             };
           }

modules/nixosModules.nix

@@ -20,6 +20,8 @@ in
         apply = mapAttrs (k: v: { _file = "${toString self.outPath}/flake.nix#nixosModules.${k}"; imports = [ v ]; });
         description = ''
           NixOS modules.
+
+          You may use this for reusable pieces of configuration, service modules, etc.
         '';
       };
     };

modules/overlays.nix

@@ -24,12 +24,12 @@ in
           }
         '';
         description = ''
-          An attribute set of overlays.
+          An attribute set of [overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays).
 
           Note that the overlays themselves are not mergeable. While overlays
           can be composed, the order of composition is significant, but the
           module system does not guarantee sufficiently deterministic
-          definition ordering, across versions and when changing <literal>imports</literal>.
+          definition ordering, across versions and when changing `imports`.
         '';
       };
     };

modules/packages.nix

@@ -14,8 +14,9 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf types.package;
     default = { };
     description = ''
-      An attribute set of packages to be built by <literal>nix build .#&lt;name></literal>.
+      An attribute set of packages to be built by [`nix build`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
-      <literal>nix build .#&lt;name></literal> will build <literal>packages.&lt;name></literal>.
+
+      `nix build .#<name>` will build `packages.<name>`.
     '';
   };
   file = ./packages.nix;

modules/perSystem.nix

@@ -16,17 +16,21 @@ in
 {
   options = {
     systems = mkOption {
-      description = "All the system types to enumerate in the flake.";
+      description = ''
+        All the system types to enumerate in the flake output subattributes.
+
+        In other words, all valid values for `system` in e.g. `packages.<system>.foo`.
+      '';
       type = types.listOf types.str;
     };
 
     perInput = mkOption {
-      description = "Function from system to function from flake to <literal>system</literal>-specific attributes.";
+      description = "Function from system to function from flake to `system`-specific attributes.";
       type = types.functionTo (types.functionTo (types.lazyAttrsOf types.unspecified));
     };
 
     perSystem = mkOption {
-      description = "A function from system to flake-like attributes omitting the <literal>&lt;system></literal> attribute.";
+      description = "A function from system to flake-like attributes omitting the `<system>` attribute.";
       type = mkPerSystemType ({ config, system, ... }: {
         _file = ./perSystem.nix;
         config = {

modules/transposition.nix

@@ -18,11 +18,11 @@ let
         type = types.bool;
         default = false;
         description = ''
-          Whether to provide a stub option declaration for <option>perSystem.&lt;name></option>
+          Whether to provide a stub option declaration for {option}`perSystem.<name>`.
 
           The stub option declaration does not support merging and lacks
-          documentation, so you are recommended to declare the <option>perSystem.&lt;name></option>
+          documentation, so you are recommended to declare the {option}`perSystem.<name>`
-          option yourself and avoid <option>adHoc</option>.
+          option yourself and avoid {option}`adHoc`.
         '';
       };
     };
@@ -38,12 +38,12 @@ in
         Transposition is the operation that swaps the indices of a data structure.
         Here it refers specifically to the transposition between
 
-        <literal>
+        ```plain
-          perSystem: .''${system}.''${attribute}
+        perSystem: .''${system}.''${attribute}
-          outputs:   .''${attribute}.''${system}
+        outputs:   .''${attribute}.''${system}
-        </literal>
+        ```
 
-        It also defines the reverse operation in <option>perInput</option>.
+        It also defines the reverse operation in [{option}`perInput`](#opt-perInput).
       '';
       type =
         types.lazyAttrsOf

site/flake-module.nix

@@ -16,15 +16,16 @@
         let sourcePathStr = toString sourcePath;
         in
         opt:
-        let declarations = concatMap
+        let
-          (decl:
+          declarations = concatMap
-            if hasPrefix sourcePathStr (toString decl)
+            (decl:
-            then
+              if hasPrefix sourcePathStr (toString decl)
-              let subpath = removePrefix sourcePathStr (toString decl);
+              then
-              in [{ url = baseUrl + subpath; name = sourceName + subpath; }]
+                let subpath = removePrefix sourcePathStr (toString decl);
-            else [ ]
+                in [{ url = baseUrl + subpath; name = sourceName + subpath; }]
-          )
+              else [ ]
-          opt.declarations;
+            )
+            opt.declarations;
         in
         if declarations == [ ]
         then opt // { visible = false; }
@@ -39,6 +40,8 @@
             transformOptions = filterTransformOptions {
               inherit sourceName baseUrl sourcePath;
             };
+            warningsAreErrors = true; # not sure if feasible long term
+            markdownByDefault = true;
           }).optionsDocBook;
           inherit title;
         } ''