Tooling for translations

.github/workflows/ci.yaml

@@ -19,6 +19,7 @@ jobs:
     - uses: cachix/install-nix-action@v25
     - run: nix-env -f default.nix -iA build
     - run: postgrest-docs-build
+    - run: git diff --exit-code HEAD locales || echo "Please commit changes to the locales/ folder after running postgrest-docs-build."
 
   spellcheck:
     name: Run spellcheck

.gitignore

@@ -6,3 +6,4 @@ diagrams/db.pdf
 misspellings
 unuseddict
 .history
+*.mo

README.md

@@ -18,3 +18,21 @@ Once in the nix-shell you have the following commands available:
 
 This documentation is structured according to tutorials-howtos-topics-references. For more details on the rationale of this structure, 
 see https://www.divio.com/blog/documentation.
+
+## Translating
+
+To create `.po` files for translation into a new language pass the language code as the first argument to `postgrest-docs-build`.
+
+Example to add German/de:
+
+```
+postgrest-docs-build de
+```
+
+The livereload server also supports a language/locale argument to show the translated docs during translation:
+
+```
+postgrest-docs-serve de
+```
+
+Spellcheck is currently only available for the default language.

build.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# sphinx-intl fails if LC_ALL is not set
+export LC_ALL=${LC_ALL:-C}
+
+function build() {
+  sphinx-build --color -W -a -n docs -b "$@"
+}
+
+if [ $# -eq 0 ]; then
+  # clean previous build, otherwise some errors might be supressed
+  rm -rf "_build/html/default"
+
+  if [ -d languages ]; then
+    # default to updating all existing locales
+    build gettext _build/gettext
+    sphinx-intl update -p _build/gettext
+  fi
+
+  build html "_build/html/default"
+else
+  # clean previous build, otherwise some errors might be supressed
+  rm -rf "_build/html/$1"
+
+  # update and build specific locale, can be used to create new locale
+  build gettext _build/gettext
+  sphinx-intl update -p _build/gettext -l "$1"
+
+  build html "_build/html/$1" -D "language=$1"
+fi

default.nix

@@ -1,9 +1,9 @@
 let
   # Commit of the Nixpkgs repository that we want to use.
   nixpkgsVersion = {
-    date = "2023-03-25";
-    rev = "dbf5322e93bcc6cfc52268367a8ad21c09d76fea";
-    tarballHash = "0lwk4v9dkvd28xpqch0b0jrac4xl9lwm6snrnzx8k5lby72kmkng";
+    date = "2024-01-06";
+    rev = "4bbf5a2eb6046c54f7a29a0964c642ebfe912cbc";
+    tarballHash = "03p45qdcxqxc41mmzmmyzbkff29vv95vv643z0kd3mf1s2nnsy5b";
   };
 
   # Nix files that describe the Nixpkgs repository. We evaluate the expression
@@ -15,7 +15,16 @@ let
     })
     { };
 
-  python = pkgs.python3.withPackages (ps: [ ps.sphinx ps.sphinx_rtd_theme ps.livereload ps.sphinx-tabs ps.sphinx-copybutton ps.sphinxext-opengraph ]);
+  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;
@@ -25,10 +34,10 @@ rec {
       ''
         set -euo pipefail
 
-        # clean previous build, otherwise some errors might be supressed
-        rm -rf _build
+        # build.sh needs to find "sphinx-build"
+        PATH=${python}/bin:$PATH
 
-        ${python}/bin/sphinx-build --color -W -b html -a -n docs _build
+        ./build.sh "$@"
       '';
 
   serve =
@@ -39,7 +48,7 @@ rec {
         # livereload_docs.py needs to find "sphinx-build"
         PATH=${python}/bin:$PATH
 
-        ${python}/bin/python livereload_docs.py
+        ./livereload_docs.py "$@"
       '';
 
   spellcheck =

docs/conf.py

@@ -297,6 +297,10 @@ def setup(app):
 # taken from https://github.com/sphinx-doc/sphinx/blob/82dad44e5bd3776ecb6fd8ded656bc8151d0e63d/sphinx/util/requests.py#L42
 user_agent = 'Mozilla/5.0 (X11; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0'
 
+# TODO: stackoverflow only returns 403 right now. We might need to come back later to check whether that's
+# a permanent issue or not.
+linkcheck_ignore = [r'https://stackoverflow.com/']
+
 # sphinx-tabs configuration
 sphinx_tabs_disable_tab_closing = True
 

docs/how-tos/sql-user-management-using-postgres-users-and-passwords.rst

@@ -52,7 +52,7 @@ Concerning the `pgjwt extension <https://github.com/michelp/pgjwt>`_, please cf.
   CREATE EXTENSION IF NOT EXISTS pgjwt WITH SCHEMA ext_pgjwt;
 
 
-In order to be able to work with postgres' SCRAM-SHA-256 password hashes, we also need the PBKDF2 key derivation function. Luckily there is `a PL/pgSQL implementation on stackoverflow <https://stackoverflow.com/q/47162200/2337147>`_:
+In order to be able to work with postgres' SCRAM-SHA-256 password hashes, we also need the PBKDF2 key derivation function. Luckily there is `a PL/pgSQL implementation on stackoverflow <https://stackoverflow.com/a/72805848>`_:
 
 .. code-block:: plpgsql
 

livereload_docs.py

@@ -1,10 +1,18 @@
 #!/usr/bin/env python
+import sys
 from livereload import Server, shell
 from subprocess import call
-## Build docs at startup
-call(['sphinx-build', '-b', 'html', '-a', '-n', 'docs', '_build'])
+
+if len(sys.argv) == 1:
+    locale = 'default'
+    build = './build.sh'
+else:
+    locale = sys.argv[1]
+    build = f'./build.sh {locale}'
+
+call(build, shell=True)
+
 server = Server()
-server.watch('docs/**/*.rst', shell('sphinx-build -b html -a -n docs _build'))
-# For custom port and host
-# server.serve(root='_build/', host='192.168.1.2')
-server.serve(root='_build/')
+server.watch('docs/**/*.rst', shell(build))
+server.watch(f'locales/{locale}/LC_MESSAGES/*.po', shell(build))
+server.serve(root=f'_build/html/{locale}')

requirements.txt

@@ -1,7 +1,8 @@
 docutils==0.17.1
-sphinx>=5.0.2
 sphinx-copybutton
+sphinx-intl
 sphinx-rtd-theme>=0.5.1
 sphinx-tabs>=3.2.0
-urllib3==2.0.7
+sphinx>=5.0.2
 sphinxext-opengraph==0.9.0
+urllib3==2.0.7