diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 000000000..2d7162fb6 --- /dev/null +++ b/.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 + diff --git a/.gitignore b/.gitignore index 00042c276..4c1f95600 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ Pipfile.lock *.aux *.log diagrams/db.pdf +misspellings diff --git a/README.md b/README.md index e8a06defb..0bf695513 100644 --- a/README.md +++ b/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 diff --git a/circle.yml b/circle.yml deleted file mode 100644 index ae7ac312b..000000000 --- a/circle.yml +++ /dev/null @@ -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 diff --git a/default.nix b/default.nix index 9bc5b1c42..62a18d814 100644 --- a/default.nix +++ b/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 + ''; } diff --git a/postgrest.dict b/postgrest.dict index 0faacadb5..03dbef3d3 100644 --- a/postgrest.dict +++ b/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 diff --git a/shell.nix b/shell.nix new file mode 100644 index 000000000..37e6d7cbb --- /dev/null +++ b/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 + ]; +}