jimmy/postgrest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

nix: Move docs tools into core infrastructure

Browse Source
This commit is contained in:
Laurence Isla
2024-02-18 13:10:00 +01:00
committed by Wolfgang Walther
parent e110fdbd2c
commit a1f2ecadda
11 changed files with 170 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/docs.yaml
+16 -9
View File
@@ -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
default.nix
+4
View File
@@ -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
-1
View File
@@ -5,5 +5,4 @@ Pipfile.lock
_diagrams/db.pdf
misspellings
unuseddict
.history
*.mo
docs/README.md
+1 -11
View File
@@ -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
docs/build.sh
+1 -1
View File
@@ -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
-109
View File
@@ -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
+1 -1
View File
@@ -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
-22
View File
@@ -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
+21
View File
@@ -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
+125
View File
@@ -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
+1
View File
@@ -21,6 +21,7 @@ let
[
postgrest.cabalTools
postgrest.devTools
postgrest.docs
postgrest.loadtest
postgrest.nixpkgsTools
postgrest.style