chore: Add build tools for translations

Signed-off-by: Wolfgang Walther <[email protected]>

Author: wolfgangwalther

Diff for: .gitignore

@@ -4,3 +4,4 @@ Pipfile.lock
 *.log
 diagrams/db.pdf
 misspellings
+*.mo

Diff for: 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.

Diff for: build.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+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"
+
+  # default to updating all existing locales
+  build gettext _build/gettext
+  sphinx-intl update -p _build/gettext
+
+  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

Diff for: default.nix

@@ -17,8 +17,16 @@ let
 
   sphinxTabsPkg = ps: ps.callPackage ./extensions/sphinx-tabs.nix {};
   sphinxCopybuttonPkg = ps: ps.callPackage ./extensions/sphinx-copybutton.nix {};
-
-  python = pkgs.python3.withPackages (ps: [ ps.sphinx ps.sphinx_rtd_theme ps.livereload (sphinxTabsPkg ps) (sphinxCopybuttonPkg ps) ]);
+  sphinxIntlPkg = ps: ps.callPackage ./extensions/sphinx-intl.nix {};
+
+  python = pkgs.python3.withPackages (ps: [
+    ps.sphinx
+    ps.sphinx_rtd_theme
+    ps.livereload
+    (sphinxTabsPkg ps)
+    (sphinxCopybuttonPkg ps)
+    (sphinxIntlPkg ps)
+  ]);
 in
 {
   inherit pkgs;
@@ -28,10 +36,10 @@ in
       ''
         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 =
@@ -42,7 +50,7 @@ in
         # livereload_docs.py needs to find "sphinx-build"
         PATH=${python}/bin:$PATH
 
-        ${python}/bin/python livereload_docs.py
+        ./livereload_docs.py "$@"
       '';
 
   spellcheck =

Diff for: extensions/sphinx-intl.nix

@@ -0,0 +1,29 @@
+{ buildPythonPackage
+, click
+, fetchPypi
+, lib
+, sphinx
+}:
+
+buildPythonPackage rec {
+  pname = "sphinx-intl";
+  version = "2.0.1";
+
+  src = fetchPypi {
+    inherit pname version;
+    sha256 = "sha256:1d1q0sanjp4nkfvhsxi75zf3xjyyi8nzxvl3v7l0jy9ld70nwnmj";
+  };
+
+  propagatedBuildInputs = [
+    click
+    sphinx
+  ];
+
+  doCheck = false;
+
+  meta = with lib; {
+    description = "Sphinx utility that make it easy to translate and to apply translation.";
+    homepage = "https://sphinx-intl.readthedocs.io";
+    license = licenses.bsd2;
+  };
+}

Diff for: livereload_docs.py

@@ -1,13 +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('*.rst', shell('sphinx-build -b html -a -n docs _build'))
-server.watch('tutorials/*.rst', shell('sphinx-build -b html -a -n docs _build'))
-server.watch('how-tos/*.rst', shell('sphinx-build -b html -a -n docs _build'))
-server.watch('releases/*.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}')

Diff for: requirements.txt

@@ -1,3 +1,4 @@
 docutils<0.18
 sphinx-tabs
-sphinx-copybutton
+sphinx-copybutton
+sphinx-intl