Add nix-shell tools, fix circleci, resolves #322

.circleci/config.yml

@@ -0,0 +1,33 @@
+version: 2.1
+
+jobs:
+  build:
+    docker:
+      - image: nixos/nix:2.3
+    steps:
+      - checkout
+      - run:
+          name: Install build script
+          command: nix-env -f default.nix -iA build
+      - run:
+          name: Build docs
+          command: postgrest-docs-build
+
+  spellcheck:
+    docker:
+      - image: nixos/nix:2.3
+    steps:
+      - checkout
+      - run:
+          name: Install spellcheck script
+          command: nix-env -f default.nix -iA spellcheck
+      - run:
+          name: Run spellcheck
+          command: postgrest-docs-spellcheck
+
+workflows:
+  check:
+    jobs:
+      - build
+      - spellcheck
+

.gitignore

@@ -3,3 +3,4 @@ Pipfile.lock
 *.aux
 *.log
 diagrams/db.pdf
+misspellings

README.md

@@ -2,20 +2,17 @@
 
 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.
 
-You can use [pipenv](https://pipenv.readthedocs.io) to build the docs locally:
-
-```bash
-  pipenv install
-  pipenv run python livereload_docs.py
-```
-
-Or if you use [nix](https://nixos.org/nix/), you can just run:
+To build the docs locally, use [nix](https://nixos.org/nix/):
 
 ```bash
   nix-shell
 ```
 
-Both of these options will build the docs and start a livereload server on `http://localhost:5500`.
+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
 

circle.yml

@@ -1,8 +0,0 @@
-dependencies:
-  pre:
-    - sudo apt-get install aspell
-
-test:
-  override:
-    - cat *.rst | grep -v '^\(\.\.\|  \)' | sed 's/`.*`//g' |aspell -d en_US -p ./postgrest.dict list | tee misspellings
-    - test ! -s misspellings

default.nix

@@ -1,17 +1,60 @@
-with import (builtins.fetchGit {
-  url = https://github.com/NixOS/nixpkgs-channels;
-  ref = "nixos-18.09-small";
-  rev = "95fed28ac372c61eb83c87ad97c24b0f957827bf";
-}) {};
+let
+  # Commit of the Nixpkgs repository that we want to use.
+  nixpkgsVersion = {
+    date = "2020-10-27";
+    rev = "cd63096d6d887d689543a0b97743d28995bc9bc3";
+    tarballHash = "1wg61h4gndm3vcprdcg7rc4s1v3jkm5xd7lw8r2f67w502y94gcy";
+  };
 
-stdenv.mkDerivation {
-  name = "postgrest-docs";
-  buildInputs = [
-    python36Full
-    python36Packages.sphinx
-    python36Packages.sphinx_rtd_theme
-    python36Packages.livereload ];
-  shellHook = ''
-    python livereload_docs.py && exit
-  '';
+  # 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 ]);
+in
+{
+  inherit pkgs;
+
+  build =
+    pkgs.writeShellScriptBin "postgrest-docs-build"
+      ''
+        set -euo pipefail
+
+        # clean previous build, otherwise some errors might be supressed
+        rm -rf _build
+
+        ${python}/bin/sphinx-build -W -b html -a -n . _build
+      '';
+
+  serve =
+    pkgs.writeShellScriptBin "postgrest-docs-serve"
+      ''
+        set -euo pipefail
+
+        # livereload_docs.py needs to find "sphinx-build"
+        PATH=${python}/bin:$PATH
+
+        ${python}/bin/python livereload_docs.py
+      '';
+
+  spellcheck =
+    pkgs.writeShellScriptBin "postgrest-docs-spellcheck"
+      ''
+        set -euo pipefail
+
+        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
+      '';
 }

postgrest.dict

@@ -1,134 +1,134 @@
 personal_ws-1.1 en 0 utf-8
 AMQP
-Auth
-Bool
-CSV
-Codd
-DDL
-DoS
-GHC
-GUC
-Github
-Google
-GraphQL
-HMAC
-HTTPS
-HV
-Haskell
-Heroku
-Homebrew
-ILIKE
-IP
-JS
-JSON
-JWK
-JWT
-Kinesis
-Logins
-MVCC
-Mithril
-NGINX
-Nginx
-OAuth
-ORM
-OpenAPI
-PaaS
-PostGIS
-PostgREST
-PostgREST's
-PostgreSQL
-PostgreSQL's
-RDS
-RESTful
-RLS
-RSA
-RabbitMQ
-RestSharp
-SHA
-SIGUSR1
-SNS
-SQL
-SSL
-Sencha
-SuperAgent
-Tcl
-TypeScript
-UI
-Vondra
-WAI
-Websockets
-ZeroMQ
 api
 aud
+Auth
 auth
 authenticator
 balancer
+Bool
 cd
 centric
+Codd
 conf
 config
 cryptographically
+CSV
 csv
+DDL
 disjoined
+DoS
 eq
 filename
 fts
+GHC
+Github
+Google
 grantor
+GraphQL
 gte
+GUC
+Haskell
+Heroku
+HMAC
+Homebrew
 http
+HTTPS
+HV
+ILIKE
 ilike
+IP
+JS
+JSON
 json
+JWK
+JWT
 jwt
+Kinesis
 localhost
 login
+Logins
 logins
 lon
 lt
 lte
 middleware
+Mithril
 multi
+MVCC
 namespaced
 neq
+NGINX
+Nginx
 ngrep
 nullsfirst
 nullslast
 nxl
 nxr
+OAuth
+OpenAPI
 openapi
+ORM
 ov
+PaaS
 param
 params
 passphrase
-pgSQL
 pgcrypto
 pgjwt
+pgSQL
 phfts
 plfts
+PostGIS
+PostgreSQL
+PostgreSQL's
+PostgREST
 postgrest
+PostgREST's
 pre
+RabbitMQ
+RDS
 reallyreallyreallyreallyverysafe
 refactor
 requester's
+RESTful
+RestSharp
+RLS
+RSA
 savepoint
 schemas
+Sencha
+SHA
 signup
+SIGUSR
 sl
+SNS
 sqitch
+SQL
 sql
 sr
+SSL
 startup
 stateful
 stdout
+SuperAgent
 syslog
+Tcl
 tsquery
+TypeScript
+UI
+ui
 unicode
+UPSERT
+Upsert
 uri
 url
 urls
 verifier
 versioning
+Vondra
+WAI
+Websockets
 webuser
 wildcard
-Upsert
-UPSERT
-ui
+ZeroMQ

shell.nix

@@ -0,0 +1,16 @@
+let
+  docs =
+    import ./default.nix;
+
+  pkgs =
+    docs.pkgs;
+in
+pkgs.mkShell {
+  name = "postgrest-docs";
+
+  buildInputs = [
+    docs.build
+    docs.serve
+    docs.spellcheck
+  ];
+}