nix: unify the docs and core nix tools

default.nix

@@ -142,6 +142,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/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/):
-
-```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.
+To build the docs locally, see [the Nix development readme](/nix/README.md#documentation). 
 
 ## Documentation structure
 

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/overlays/checked-shell-script/checked-shell-script.nix

@@ -16,6 +16,7 @@
 , args ? [ ]
 , positionalCompletion ? ""
 , inRootDir ? false
+, inDocsDir ? false
 , redirectTixFiles ? true
 , withEnv ? null
 , withPath ? [ ]
@@ -99,6 +100,10 @@ let
           fi
         ''
 
+        + lib.optionalString inDocsDir ''
+          cd "$(${git}/bin/git rev-parse --show-toplevel)/docs"
+        ''
+
         + lib.optionalString withTmpDir ''
           mkdir -p "''${TMPDIR:-/tmp}/postgrest"
           tmpdir="$(${coreutils}/bin/mktemp -d --tmpdir postgrest/${name}-XXX)"

nix/tools/docs.nix

@@ -0,0 +1,125 @@
+{ buildToolbox
+, checkedShellScript
+, python3
+, aspell
+, aspellDicts
+}:
+let
+  python = python3.withPackages (ps: [
+    ps.sphinx
+    ps.sphinx_rtd_theme
+    ps.livereload
+    ps.sphinx-tabs
+    ps.sphinx-copybutton
+    ps.sphinxext-opengraph
+  ]);
+
+  build =
+    checkedShellScript
+      {
+        name = "postgrest-docs-build";
+        docs = "Clean and build the documentation.";
+        inDocsDir = true;
+      }
+      ''
+        # clean previous build, otherwise some errors might be supressed
+        rm -rf _build
+
+        ${python}/bin/sphinx-build --color -W -b html -a -n docs _build
+      '';
+
+  serve =
+    checkedShellScript
+      {
+        name = "postgrest-docs-serve";
+        docs = "Serve the documentation locally with live reload.";
+        inDocsDir = true;
+      }
+      ''
+        # livereload_docs.py needs to find "sphinx-build"
+        PATH=${python}/bin:$PATH
+
+        ${python}/bin/python livereload_docs.py
+      '';
+
+  spellcheck =
+    checkedShellScript
+      {
+        name = "postgrest-docs-spellcheck";
+        docs = "Verify spelling mistakes. Bypass if the word is present in postgrest.dict";
+        inDocsDir = true;
+      }
+      ''
+        FILES=$(find docs -type f -iname '*.rst' | tr '\n' ' ')
+
+        # shellcheck disable=SC2016
+        # shellcheck disable=SC2002
+        # shellcheck disable=SC2086
+        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.";
+        inDocsDir = true;
+      }
+      ''
+        FILES=$(find docs -type f -iname '*.rst' | tr '\n' ' ')
+
+        # shellcheck disable=SC2002
+        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 =
+    checkedShellScript
+      {
+        name = "postgrest-docs-linkcheck";
+        docs = "Verify that external links are working correctly.";
+        inDocsDir = true;
+      }
+      ''
+        ${python}/bin/sphinx-build --color -b linkcheck docs _build
+      '';
+
+  check =
+    checkedShellScript
+      {
+        name = "postgrest-docs-check";
+        docs = "Build and run all the validation scripts.";
+        inDocsDir = true;
+      }
+      ''
+        ${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
+      serve
+      spellcheck
+      dictcheck
+      linkcheck
+      check
+    ];
+}

shell.nix

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