Add docs to all checked shell scripts in nix

nix/UPGRADE.md

@@ -5,7 +5,7 @@ should be a very simple operation.
 
 ```bash
 # Update pinned version of Nixpkgs
-nix-shell --run nixpkgs-upgrade > nix/nixpkgs-version.nix
+nix-shell --run postgrest-nixpkgs-upgrade
 
 # Verify that everything builds
 nix-build
@@ -27,7 +27,7 @@ the complete Git repository. To upgrade it to the current `master` of
 nix-shell
 
 # Run the utility script to pin the latest revision in master
-nixpkgs-upgrade > nix/nixpkgs-version.nix
+postgrest-nixpkgs-upgrade
 
 # Exit the nix-shell with Ctrl-d
 

nix/devtools.nix

@@ -9,7 +9,20 @@
 }:
 let
   watch =
-    checkedShellScript "postgrest-watch"
+    checkedShellScript
+      {
+        name = "postgrest-watch";
+        docs =
+          ''
+            Watch the project for changes and reinvoke the given command.
+
+            Example:
+
+              postgrest-watch postgrest-test-io
+
+          '';
+        inRootDir = true;
+      }
       ''
         while true; do
           (! ${silver-searcher}/bin/ag -l . | ${entr}/bin/entr -dr "$@")
@@ -17,28 +30,63 @@ let
       '';
 
   pushCachix =
-    checkedShellScript "postgrest-push-cachix"
+    checkedShellScript
+      {
+        name = "postgrest-push-cachix";
+        docs = ''
+          Push all build artifacts to cachix.
+
+          Requires that the CACHIX_SIGNING_KEY for postgrest is set as an
+          environment variable.
+        '';
+        inRootDir = true;
+      }
       ''
-        nix-store -qR --include-outputs "$(nix-instantiate)" \
+        nix-store -qR --include-outputs "$(nix-instantiate)" | cachix push postgrest
-          | cachix push postgrest
       '';
 
   build =
-    checkedShellScript "postgrest-build"
+    checkedShellScript
+      {
+        name = "postgrest-build";
+        docs = "Build PostgREST interactively using cabal-install.";
+        inRootDir = true;
+      }
       ''exec ${cabal-install}/bin/cabal v2-build ${devCabalOptions} "$@"'';
 
   run =
-    checkedShellScript "postgrest-run"
+    checkedShellScript
+      {
+        name = "postgrest-run";
+        docs = "Run PostgREST after buidling it interactively with cabal-install";
+        inRootDir = true;
+      }
       ''exec ${cabal-install}/bin/cabal v2-run ${devCabalOptions} --verbose=0 -- postgrest "$@"'';
 
   clean =
-    checkedShellScript "postgrest-clean"
+    checkedShellScript
+      {
+        name = "postgrest-clean";
+        docs = "Clean the PostgREST project, including all cabal-install artifacts.";
+        inRootDir = true;
+      }
       ''
         ${cabal-install}/bin/cabal v2-clean
       '';
 
   check =
-    checkedShellScript "postgrest-check"
+    checkedShellScript
+      {
+        name = "postgrest-check";
+        docs =
+          ''
+            Run most checks that will also run on CI.
+
+            This currently excludes the memory tests, as those are particularly
+            expensive.
+          '';
+        inRootDir = true;
+      }
       ''
         ${tests}/bin/postgrest-test-spec-all
         ${tests}/bin/postgrest-test-spec-idempotence

nix/docker/default.nix

@@ -28,9 +28,12 @@ let
       };
     };
 
-  # Helper script for loading the image.
   load =
-    checkedShellScript "postgrest-docker-load"
+    checkedShellScript
+      {
+        name = "postgrest-docker-load";
+        docs = "Load the PostgREST image into Docker.";
+      }
       ''
         docker load -i ${image}
       '';

nix/nixpkgs-upgrade.nix

@@ -10,7 +10,7 @@
 # to pin.
 let
   name =
-    "nixpkgs-upgrade";
+    "postgrest-nixpkgs-upgrade";
 
   refUrl =
     https://api.github.com/repos/nixos/nixpkgs/git/ref/heads/nixpkgs-unstable;
@@ -23,14 +23,18 @@ let
 
   script =
     checkedShellScript
-      name
+      {
+        inherit name;
+        docs = "Pin the newest unstable version of Nixpkgs.";
+        inRootDir = true;
+      }
       ''
         commitHash="$(${curl}/bin/curl "${refUrl}" -H "${githubV3Header}" | ${jq}/bin/jq -r .object.sha)"
         tarballUrl="${tarballUrlBase}$commitHash.tar.gz"
         tarballHash="$(${nix}/bin/nix-prefetch-url --unpack "$tarballUrl")"
         currentDate="$(date --iso)"
 
-        cat << EOF
+        cat > nix/nixpkgs-version.nix << EOF
         # Pinned version of Nixpkgs, generated with ${name}.
         {
           date = "$currentDate";

nix/overlays/checked-shell-script/checked-shell-script.nix

@@ -2,13 +2,15 @@
 # directly, or use the .bin attribute to get the script in a bin/ directory,
 # to be used in a path for example.
 { git
+, lib
 , runCommand
 , runtimeShell
 , shellcheck
 , stdenv
 , writeTextFile
 }:
-name: text:
+{ name, docs, inRootDir ? false }: text:
+# TODO: do something sensible with docs, e.g. provide automated --help
 let
   bin =
     writeTextFile {
@@ -20,7 +22,8 @@ let
         ''
           #!${runtimeShell}
           set -euo pipefail
-
+        ''
+        + lib.optionalString inRootDir ''
           cd "$(${git}/bin/git rev-parse --show-toplevel)"
 
           if test ! -f postgrest.cabal; then
@@ -28,9 +31,8 @@ let
                      "run this command somewhere in the PostgREST repo."
             exit 1
           fi
-
+        ''
-          ${text}
+        + text;
-        '';
 
       checkPhase =
         ''

nix/release/default.nix

@@ -9,9 +9,13 @@
 , checkedShellScript
 }:
 let
-  # Script for publishing a new release on GitHub.
   github =
-    checkedShellScript "postgrest-release-github"
+    checkedShellScript
+      {
+        name = "postgrest-release-github";
+        docs = "Push a new release to GitHub.";
+        inRootDir = true;
+      }
       ''
         version=$1
 
@@ -43,17 +47,29 @@ let
         fi
       '';
 
-  # Wrapper for login with docker. $DOCKER_USER/$DOCKER_PASS vars come from CircleCI.
-  # The DOCKER_USER is not the same as DOCKER_REPO because we use the https://hub.docker.com/u/postgrestbot account for uploading to dockerhub.
   dockerLogin =
-    checkedShellScript "postgrest-docker-login"
+    checkedShellScript
+      {
+        name = "postgrest-docker-login";
+        docs =
+          ''
+            Log in to Docker Hub using the DOCKER_USER and DOCKER_PASS env vars.
+
+            Those env vars are usually provided by CircleCI. The DOCKER_USER is
+            not the same as DOCKER_REPO because we use the
+            https://hub.docker.com/u/postgrestbot account for uploading to dockerhub.
+          '';
+      }
       ''
         docker login -u "$DOCKER_USER" -p "$DOCKER_PASS"
       '';
 
-  # Script for publishing a new release on Docker Hub.
   dockerHub =
-    checkedShellScript "postgrest-release-dockerhub"
+    checkedShellScript
+      {
+        name = "postgrest-release-dockerhub";
+        docs = "Push a new release to Docker Hub";
+      }
       ''
         version=$1
 
@@ -74,7 +90,6 @@ let
         fi
       '';
 
-  # Script for updating the repository description on Docker Hub.
   dockerHubDescription =
     let
       description =
@@ -83,7 +98,11 @@ let
       fullDescription =
         ./docker-hub-full-description.md;
     in
-    checkedShellScript "postgrest-release-dockerhubdescription"
+    checkedShellScript
+      {
+        name = "postgrest-release-dockerhubdescription";
+        docs = "Update the repository description on Docker Hub.";
+      }
       ''
         # Login to Docker Hub and get a token.
         token="$(

nix/style.nix

@@ -9,7 +9,12 @@
 }:
 let
   style =
-    checkedShellScript "postgrest-style"
+    checkedShellScript
+      {
+        name = "postgrest-style";
+        docs = "Automatically format Haskell, Nix and Python files.";
+        inRootDir = true;
+      }
       ''
         # Format Nix files
         ${nixpkgs-fmt}/bin/nixpkgs-fmt . > /dev/null 2> /dev/null
@@ -25,7 +30,12 @@ let
 
   # Script to check whether any uncommited changes result from postgrest-style
   styleCheck =
-    checkedShellScript "postgrest-style-check"
+    checkedShellScript
+      {
+        name = "postgrest-style-check";
+        docs = "Check whether postgrest-style results in any uncommited changes.";
+        inRootDir = true;
+      }
       ''
         ${style}
 
@@ -33,7 +43,12 @@ let
       '';
 
   lint =
-    checkedShellScript "postgrest-lint"
+    checkedShellScript
+      {
+        name = "postgrest-lint";
+        docs = "Lint all Haskell files.";
+        inRootDir = true;
+      }
       ''
         # Lint Haskell files
         # --vimgrep fixes a bug in ag: https://github.com/ggreer/the_silver_searcher/issues/753

nix/tests.nix

@@ -22,11 +22,16 @@ let
   # Wrap the `test/with_tmp_db` script with the required dependencies from Nix.
   withTmpDb =
     postgresql:
-    checkedShellScript "postgrest-test-${postgresql.name}"
+    checkedShellScript
+      {
+        name = "postgrest-test-withtmpdb-${postgresql.name}";
+        docs = "Run the given command in a temporary database";
+        inRootDir = true;
+      }
       ''
         export PATH=${postgresql}/bin:"$PATH"
 
-        exec ${../test/with_tmp_db} "$@"
+        exec test/with_tmp_db "$@"
       '';
 
   # Script to run the Haskell test suite against a specific version of
@@ -34,7 +39,11 @@ let
   testSpec =
     name: postgresql:
     checkedShellScript
-      name
+      {
+        inherit name;
+        docs = "Run the Haskell test suite against ${postgresql.name}.";
+        inRootDir = true;
+      }
       ''
         env="$(cat ${postgrest.env})"
         export PATH="$env/bin:$PATH"
@@ -61,7 +70,11 @@ let
   testSpecIdempotence =
     name: postgrestql:
     checkedShellScript
-      name
+      {
+        inherit name;
+        docs = "Check that the Haskell tests can be run multiple times against the same db.";
+        inRootDir = true;
+      }
       ''
         env="$(cat ${postgrest.env})"
         export PATH="$env/bin:$PATH"
@@ -85,7 +98,12 @@ let
       testRunners =
         map (test: "${test}/bin/${test.name}") testSpecVersions;
     in
-    checkedShellScript "postgrest-test-spec-all"
+    checkedShellScript
+      {
+        name = "postgrest-test-spec-all";
+        docs = "Run the Haskell tests against all supported PostgreSQL versions.";
+        inRootDir = true;
+      }
       (lib.concatStringsSep "\n" testRunners);
 
   ioTestPython =
@@ -101,7 +119,11 @@ let
   testIO =
     name: postgresql:
     checkedShellScript
-      name
+      {
+        inherit name;
+        docs = "Run the pytest-based IO tests.";
+        inRootDir = true;
+      }
       ''
         env="$(cat ${postgrest.env})"
         export PATH="$env/bin:$PATH"
@@ -114,7 +136,11 @@ let
   testMemory =
     name: postgresql:
     checkedShellScript
-      name
+      {
+        inherit name;
+        docs = "Run the memory tests.";
+        inRootDir = true;
+      }
       ''
         export PATH="${postgrestProfiled}/bin:${curl}/bin:$PATH"
 
@@ -124,7 +150,11 @@ let
   dumpSchema =
     name: postgresql:
     checkedShellScript
-      name
+      {
+        inherit name;
+        docs = "Dump the loaded schema's DbStructure as a yaml file.";
+        inRootDir = true;
+      }
       ''
         env="$(cat ${postgrest.env})"
         export PATH="$env/bin:$PATH"