nix: Move docs tools into core infrastructure

.github/workflows/docs.yaml

@@ -16,8 +16,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: cachix/install-nix-action@v25
+    - name: Setup Nix Environment
-    - run: nix-env -f docs/default.nix -iA build
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: docs
     - run: postgrest-docs-build
     - run: git diff --exit-code HEAD locales || echo "Please commit changes to the locales/ folder after running postgrest-docs-build."
 
@@ -26,8 +28,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: cachix/install-nix-action@v25
+    - name: Setup Nix Environment
-    - run: nix-env -f docs/default.nix -iA spellcheck
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: docs
     - run: postgrest-docs-spellcheck
 
   dictcheck:
@@ -35,8 +39,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: cachix/install-nix-action@v25
+      - name: Setup Nix Environment
-      - run: nix-env -f docs/default.nix -iA dictcheck
+        uses: ./.github/actions/setup-nix
+        with:
+          tools: docs
       - run: postgrest-docs-dictcheck
 
   linkcheck:
@@ -45,7 +51,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: cachix/install-nix-action@v25
+    - name: Setup Nix Environment
-    - run: nix-env -f docs/default.nix -iA linkcheck
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: docs
     - run: postgrest-docs-linkcheck
-    

default.nix

@@ -124,6 +124,10 @@ rec {
   devTools =
     pkgs.callPackage nix/tools/devTools.nix { inherit tests style devCabalOptions hsie withTools; };
 
+  # Documentation tools.
+  docs =
+    pkgs.callPackage nix/tools/docs.nix { };
+
   # Load testing tools.
   loadtest =
     pkgs.callPackage nix/tools/loadtest.nix { inherit withTools; };

docs/.gitignore

@@ -5,5 +5,4 @@ Pipfile.lock
 _diagrams/db.pdf
 misspellings
 unuseddict
-.history
 *.mo

docs/README.md

@@ -2,17 +2,7 @@
 
 PostgREST docs use the reStructuredText format, check this [cheatsheet](https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst) to get acquainted with it.
 
-To build the docs locally, use [nix](https://nixos.org/nix/):
+To build the docs locally, see [the Nix development readme](/nix/README.md#documentation).
-
-```bash
-  nix-shell
-```
-
-Once in the nix-shell you have the following commands available:
-
-- `postgrest-docs-build`: Build the docs.
-- `postgrest-docs-serve`: Build the docs and start a livereload server on `http://localhost:5500`.
-- `postgrest-docs-spellcheck`: Run aspell.
 
 ## Documentation structure
 

docs/build.sh

@@ -8,7 +8,7 @@ function build() {
   sphinx-build --color -W -a -n . -b "$@"
 }
 
-if [ $# -eq 0 ]; then
+if [ "${1:-}" == "" ]; then
   # clean previous build, otherwise some errors might be supressed
   rm -rf "_build/html/default"
 

docs/default.nix

@@ -1,109 +0,0 @@
-let
-  # Commit of the Nixpkgs repository that we want to use.
-  nixpkgsVersion = {
-    date = "2024-01-06";
-    rev = "4bbf5a2eb6046c54f7a29a0964c642ebfe912cbc";
-    tarballHash = "03p45qdcxqxc41mmzmmyzbkff29vv95vv643z0kd3mf1s2nnsy5b";
-  };
-
-  # Nix files that describe the Nixpkgs repository. We evaluate the expression
-  # using `import` below.
-  pkgs = import
-    (fetchTarball {
-      url = "https://github.com/nixos/nixpkgs/archive/${nixpkgsVersion.rev}.tar.gz";
-      sha256 = nixpkgsVersion.tarballHash;
-    })
-    { };
-
-  python = pkgs.python3.withPackages (ps: [
-    ps.sphinx
-    ps.sphinx_rtd_theme
-    ps.livereload
-    ps.sphinx-tabs
-    ps.sphinx-copybutton
-    ps.sphinxext-opengraph
-    # TODO: Remove override once new sphinx-intl version (> 2.1.0) is released and available in nixpkgs
-    (ps.sphinx-intl.overrideAttrs (drv: { nativeBuildInputs = drv.nativeBuildInputs ++ [ ps.six ]; }))
-  ]);
-in
-rec {
-  inherit pkgs;
-
-  build =
-    pkgs.writeShellScriptBin "postgrest-docs-build"
-      ''
-        set -euo pipefail
-        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
-
-        # build.sh needs to find "sphinx-build"
-        PATH=${python}/bin:$PATH
-
-        ./build.sh "$@"
-      '';
-
-  serve =
-    pkgs.writeShellScriptBin "postgrest-docs-serve"
-      ''
-        set -euo pipefail
-        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
-
-        # livereload_docs.py needs to find "sphinx-build"
-        PATH=${python}/bin:$PATH
-
-        ./livereload_docs.py "$@"
-      '';
-
-  spellcheck =
-    pkgs.writeShellScriptBin "postgrest-docs-spellcheck"
-      ''
-        set -euo pipefail
-        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
-
-        FILES=$(find . -type f -iname '*.rst' | tr '\n' ' ')
-
-        cat $FILES \
-         | grep -v '^\(\.\.\|  \)' \
-         | sed 's/`.*`//g' \
-         | ${pkgs.aspell}/bin/aspell -d ${pkgs.aspellDicts.en}/lib/aspell/en_US -p ./postgrest.dict list \
-         | sort -f \
-         | tee misspellings
-        test ! -s misspellings
-      '';
-
-  # dictcheck detects obsolete entries in postgrest.dict, that are not used anymore
-  dictcheck =
-    pkgs.writeShellScriptBin "postgrest-docs-dictcheck"
-      ''
-        set -euo pipefail
-        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
-
-        FILES=$(find . -type f -iname '*.rst' | tr '\n' ' ')
-
-        cat postgrest.dict \
-         | tail -n+2 \
-         | tr '\n' '\0' \
-         | xargs -0 -n 1 -i \
-           sh -c "grep \"{}\" $FILES > /dev/null || echo \"{}\"" \
-         | tee unuseddict
-        test ! -s unuseddict
-      '';
-
-  linkcheck =
-    pkgs.writeShellScriptBin "postgrest-docs-linkcheck"
-      ''
-        set -euo pipefail
-        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
-
-        ${python}/bin/sphinx-build --color -b linkcheck . _build
-      '';
-
-  check =
-    pkgs.writeShellScriptBin "postgrest-docs-check"
-      ''
-        set -euo pipefail
-        ${build}/bin/postgrest-docs-build
-        ${dictcheck}/bin/postgrest-docs-dictcheck
-        ${linkcheck}/bin/postgrest-docs-linkcheck
-        ${spellcheck}/bin/postgrest-docs-spellcheck
-      '';
-}

docs/livereload_docs.py

@@ -3,7 +3,7 @@ import sys
 from livereload import Server, shell
 from subprocess import call
 
-if len(sys.argv) == 1:
+if len(sys.argv) == 1 or sys.argv[1] == "":
     locale = "default"
     build = "./build.sh"
 else:

docs/shell.nix

@@ -1,22 +0,0 @@
-let
-  docs =
-    import ./default.nix;
-
-  inherit (docs) pkgs;
-in
-pkgs.mkShell {
-  name = "postgrest-docs";
-
-  buildInputs = [
-    docs.build
-    docs.serve
-    docs.spellcheck
-    docs.dictcheck
-    docs.linkcheck
-    docs.check
-  ];
-
-  shellHook = ''
-    export HISTFILE=.history
-  '';
-}

nix/README.md

@@ -248,6 +248,27 @@ $ nix-shell --run postgrest-style
 There is also `postgrest-style-check` that exits with a non-zero exit code if
 the check resulted in any uncommitted changes. It's mostly useful for CI.
 
+## Documentation
+
+The following commands can help you when working on the PostgREST docs:
+
+```bash
+# Build the docs
+[nix-shell]$ postgrest-docs-build
+
+# Build the docs and start a livereload server on `http://localhost:5500`
+[nix-shell]$ postgrest-docs-serve
+
+# Run aspell, to verify spelling mistakes
+[nix-shell]$ postgrest-docs-spellcheck
+
+# Detect obsolete entries in postgrest.dict
+[nix-shell]$ postgrest-docs-dictcheck
+
+# Build and run all the validation scripts
+[nix-shell]$ postgrest-docs-check
+```
+
 ## General development tools
 
 Tools like `postgrest-build`, `postgrest-run`, `postgrest-repl` etc. are simple wrappers around

nix/tools/docs.nix

@@ -0,0 +1,125 @@
+{ aspell
+, aspellDicts
+, buildToolbox
+, checkedShellScript
+, python3
+}:
+let
+  python = python3.withPackages (ps: [
+    ps.sphinx
+    ps.sphinx_rtd_theme
+    ps.livereload
+    ps.sphinx-tabs
+    ps.sphinx-copybutton
+    ps.sphinxext-opengraph
+    # TODO: Remove override once new sphinx-intl version (> 2.1.0) is released and available in nixpkgs
+    (ps.sphinx-intl.overrideAttrs (drv: { nativeBuildInputs = drv.nativeBuildInputs ++ [ ps.six ]; }))
+  ]);
+
+  build =
+    checkedShellScript
+      {
+        name = "postgrest-docs-build";
+        docs = "Build the documentation.";
+        args = [ "ARG_POSITIONAL_SINGLE([language], [Language to build docs for.], [\"\"])" ];
+        workingDir = "/docs";
+      }
+      ''
+        # build.sh needs to find "sphinx-build"
+        PATH=${python}/bin:$PATH
+
+        ./build.sh "$_arg_language"
+      '';
+
+  serve =
+    checkedShellScript
+      {
+        name = "postgrest-docs-serve";
+        docs = "Serve the documentation locally with live reload.";
+        args = [ "ARG_POSITIONAL_SINGLE([language], [Language to serve docs for.], [\"\"])" ];
+        workingDir = "/docs";
+      }
+      ''
+        # livereload_docs.py needs to find "sphinx-build"
+        PATH=${python}/bin:$PATH
+
+        ./livereload_docs.py "$_arg_language"
+      '';
+
+  spellcheck =
+    checkedShellScript
+      {
+        name = "postgrest-docs-spellcheck";
+        docs = "Verify spelling mistakes. Bypass if the word is present in postgrest.dict.";
+        workingDir = "/docs";
+      }
+      ''
+        FILES=$(find . -type f -iname '*.rst' | tr '\n' ' ')
+
+        # shellcheck disable=SC2086 disable=SC2016
+        cat $FILES \
+         | grep -v '^\(\.\.\|  \)' \
+         | sed 's/`.*`//g' \
+         | ${aspell}/bin/aspell -d ${aspellDicts.en}/lib/aspell/en_US -p ./postgrest.dict list \
+         | sort -f \
+         | tee misspellings
+        test ! -s misspellings
+      '';
+
+  dictcheck =
+    checkedShellScript
+      {
+        name = "postgrest-docs-dictcheck";
+        docs = "Detect obsolete entries in postgrest.dict that are not used anymore.";
+        workingDir = "/docs";
+      }
+      ''
+        FILES=$(find . -type f -iname '*.rst' | tr '\n' ' ')
+
+        tail -n+2 postgrest.dict \
+         | tr '\n' '\0' \
+         | xargs -0 -i \
+           sh -c "grep \"{}\" $FILES > /dev/null || echo \"{}\"" \
+         | tee unuseddict
+        test ! -s unuseddict
+      '';
+
+  linkcheck =
+    checkedShellScript
+      {
+        name = "postgrest-docs-linkcheck";
+        docs = "Verify that external links are working correctly.";
+        workingDir = "/docs";
+      }
+      ''
+        ${python}/bin/sphinx-build --color -b linkcheck . _build
+      '';
+
+  check =
+    checkedShellScript
+      {
+        name = "postgrest-docs-check";
+        docs = "Build and run all the validation scripts.";
+        workingDir = "/docs";
+      }
+      ''
+        ${build}/bin/postgrest-docs-build
+        ${dictcheck}/bin/postgrest-docs-dictcheck
+        ${linkcheck}/bin/postgrest-docs-linkcheck
+        ${spellcheck}/bin/postgrest-docs-spellcheck
+      '';
+
+in
+buildToolbox
+{
+  name = "postgrest-docs";
+  tools =
+    [
+      build
+      check
+      dictcheck
+      linkcheck
+      serve
+      spellcheck
+    ];
+}

shell.nix

@@ -21,6 +21,7 @@ let
     [
       postgrest.cabalTools
       postgrest.devTools
+      postgrest.docs
       postgrest.loadtest
       postgrest.nixpkgsTools
       postgrest.style