diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index d99450c55..9d7a65fd9 100644 --- a/.github/workflows/ci.yaml +++ b/.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 diff --git a/.gitignore b/.gitignore index bab47b52e..bc77e3c24 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ diagrams/db.pdf misspellings unuseddict .history +*.mo diff --git a/README.md b/README.md index 29050fb9a..2f13bbbd9 100644 --- a/README.md +++ b/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 --git a/build.sh b/build.sh new file mode 100755 index 000000000..bbbdc9858 --- /dev/null +++ b/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 diff --git a/default.nix b/default.nix index a7d6d0007..065df64cc 100644 --- a/default.nix +++ b/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 = diff --git a/livereload_docs.py b/livereload_docs.py index 8dae16577..e7ea3911c 100755 --- a/livereload_docs.py +++ b/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}') diff --git a/requirements.txt b/requirements.txt index 48f39ed86..5eec93965 100644 --- a/requirements.txt +++ b/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