chore: Add build tools for translations

Signed-off-by: Wolfgang Walther <walther@technowledgy.de>

.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

@@ -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 =

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