From a1f2ecaddaea3234d41f8e77696e59739522cc80 Mon Sep 17 00:00:00 2001 From: Laurence Isla Date: Mon, 18 Dec 2023 16:46:09 -0500 Subject: [PATCH] nix: Move docs tools into core infrastructure --- .github/workflows/docs.yaml | 25 +++++--- default.nix | 4 ++ docs/.gitignore | 1 - docs/README.md | 12 +--- docs/build.sh | 2 +- docs/default.nix | 109 ------------------------------- docs/livereload_docs.py | 2 +- docs/shell.nix | 22 ------- nix/README.md | 21 ++++++ nix/tools/docs.nix | 125 ++++++++++++++++++++++++++++++++++++ shell.nix | 1 + 11 files changed, 170 insertions(+), 154 deletions(-) delete mode 100644 docs/default.nix delete mode 100644 docs/shell.nix create mode 100644 nix/tools/docs.nix diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 8c75b3a65..3f2057887 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -16,8 +16,10 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - uses: cachix/install-nix-action@v25 - - run: nix-env -f docs/default.nix -iA build + - name: Setup Nix Environment + 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 - - run: nix-env -f docs/default.nix -iA spellcheck + - name: Setup Nix Environment + 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 - - run: nix-env -f docs/default.nix -iA dictcheck + - name: Setup Nix Environment + 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 - - run: nix-env -f docs/default.nix -iA linkcheck + - name: Setup Nix Environment + uses: ./.github/actions/setup-nix + with: + tools: docs - run: postgrest-docs-linkcheck - diff --git a/default.nix b/default.nix index 426464a25..bcdae155f 100644 --- a/default.nix +++ b/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; }; diff --git a/docs/.gitignore b/docs/.gitignore index b07484b5e..f0ad786fb 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -5,5 +5,4 @@ Pipfile.lock _diagrams/db.pdf misspellings unuseddict -.history *.mo diff --git a/docs/README.md b/docs/README.md index 2f13bbbd9..6c7a9ea26 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/build.sh b/docs/build.sh index 6b7cf9eb1..d8addb5b7 100755 --- a/docs/build.sh +++ b/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" diff --git a/docs/default.nix b/docs/default.nix deleted file mode 100644 index eef92948d..000000000 --- a/docs/default.nix +++ /dev/null @@ -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 - ''; -} diff --git a/docs/livereload_docs.py b/docs/livereload_docs.py index 6d8abb4b2..1ee9a6b75 100755 --- a/docs/livereload_docs.py +++ b/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: diff --git a/docs/shell.nix b/docs/shell.nix deleted file mode 100644 index d74d12a4d..000000000 --- a/docs/shell.nix +++ /dev/null @@ -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 - ''; -} diff --git a/nix/README.md b/nix/README.md index f3ecee6a5..c0fab204e 100644 --- a/nix/README.md +++ b/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 diff --git a/nix/tools/docs.nix b/nix/tools/docs.nix new file mode 100644 index 000000000..7574f426b --- /dev/null +++ b/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 + ]; +} diff --git a/shell.nix b/shell.nix index c9deae547..ca71583bc 100644 --- a/shell.nix +++ b/shell.nix @@ -21,6 +21,7 @@ let [ postgrest.cabalTools postgrest.devTools + postgrest.docs postgrest.loadtest postgrest.nixpkgsTools postgrest.style