initial refactoring commit

Author: daringer

.github/workflows/build.yml

@@ -0,0 +1,170 @@
+name: build
+on:
+  push:
+    branches: [ main, develop, gh-build, fresh ]
+
+permissions:
+  contents: write
+
+jobs:
+  # runs on weblate commit
+  weblate-commit-build:
+    if: ${{ contains(github.event.head_commit.message, 'Translated using Weblate') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: TODO - start full build (delayed)
+        run: echo "TODO - start delayed full build, maybe 15mins?"
+
+  # on regular commit (auto excludes self-commited pot/po files)       
+  full-build:
+    if: ${{ ! contains(github.event.head_commit.message, 'Translated using Weblate') }}
+    concurrency:
+      group: ${{ github.ref }}
+      cancel-in-progress: true
+
+    runs-on: ubuntu-latest
+    container: 
+      image: sphinxdoc/sphinx
+      #options: --user 1001 (only if we don't need apt-get)
+
+    env:
+      MAIN_LANGS: en
+      OTHER_LANGS: de es fr ru nl it ja el bg da et fi lv lt pl pt ro sv sk sl cs hu zh_CN
+    
+    steps:
+      - name: Install git
+        run: |
+          apt-get -y update
+          apt-get -y install git ssh curl
+               
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: additional python packages
+        run: pip3 install -r requirements.txt
+          
+      - name: quick build docs
+        run: |
+          mkdir -p dist/en
+          mkdir -p build/en/doctrees
+          sphinx-build -j auto -b html -D language=en -d build/en/doctrees source dist/en
+          rm -rf dist/en/_sources
+
+      - name: upload quick build artifact 
+        id: upload-quick
+        uses: actions/upload-artifact@v4
+        with:
+          name: generated documentation (en)
+          path: dist
+
+      - name: trigger docs server to download artifact
+        uses: appleboy/[email protected]
+        with:
+          host: ${{ secrets.DOCS_HOST }}
+          username: docs
+          port: ${{ secrets.DOCS_PORT }}
+          key: ${{ secrets.DEPLOY_AUTH_KEY }}
+          script: /var/www/docs/deploy/github-trigger.sh en ${{ steps.upload-quick.outputs.artifact-id }} ${{ secrets.DOWNLOAD_TOKEN }}
+
+      - name: checkout data repository
+        uses: actions/checkout@v4
+        with:
+          repository: nitrokey/nitrokey-documentation-data
+          ref: main
+          ssh-key: ${{ secrets.DEPLOY_AUTH_KEY }}
+          path: data.git
+     
+      - name: build pot files
+        run: sphinx-build -b gettext source data.git/locales/
+
+      - name: build po files from pot files
+        shell: bash
+        run: |
+          lang=($OTHER_LANGS)
+          sphinx-intl update -p data.git/locales/ ${lang[@]/*/'-l '&' '}
+          rm -rf data.git/locales/.doctrees 
+
+      # this one looks like a upstream bug for the auto-translation 
+      # we will replace all backslashes '\\' with '/bs/' and revert
+      # this operation before actually building the language
+      # let's hope this works
+      - name: WORKAROUND - replace double backslashes in .po files
+        shell: bash
+        run: |
+          sed -ie 's@\\\\@/bs/@g' $(find data.git/locales -name "*.po" | xargs)
+
+      # - name: prepare commit data repository
+      #   run: |
+      #     cp -r locales locales.full
+      #     rm -rf locales/.doctrees
+
+      - name: commit `locales` into data repository (on changes)
+        shell: bash
+        run: |
+          #rm -rf data.git/locales
+          cd data.git
+          # not needed if run on --user 1001
+          git config --global --add safe.directory $(pwd)
+          git config --global user.name "GitHub Action"
+          git config --global user.email "[email protected]"
+          #if (git commit -m "Automated locales generation" locales); then
+          #  git push          
+          #fi
+          git status
+
+      # - name: put original `locales` back
+      #   run: |
+      #     rm -rf locales
+      #     cp -r locales.full locales
+          
+      # - name: TODO - weblate
+      #   shell: bash
+      #   run: |
+      #     # have some time for commit/push before to propagate
+      #     sleep 30
+      #     bash trigger_weblate.sh ${{ secrets.WEBLATE_API_URL }} none ${{ secrets.WEBLATE_TOKEN }} pull
+          
+      #     for lang in $OTHER_LANGS
+      #     do
+      #       bash trigger_weblate.sh ${{ secrets.WEBLATE_API_URL }} $lang ${{ secrets.WEBLATE_TOKEN }} translate
+      #     done
+
+      #     bash trigger_weblate.sh ${{ secrets.WEBLATE_API_URL }} none ${{ secrets.WEBLATE_TOKEN }} push
+
+      # - name: WORKAROUND - revert replace double backslashes in .po files
+      #   shell: bash
+      #   run: |
+      #     sed -ie 's@/bs/@\\\\@g' $(find locales -name "*.po" | xargs)
+
+      # - name: build full docs
+      #   run: |
+      #     # one _images is enough
+      #     mv dist/en/_images dist         
+          
+      #     cp -r locales source/locales
+      #     for lang in $MAIN_LANGS $OTHER_LANGS
+      #     do
+      #       mkdir -p dist/$lang
+      #       mkdir -p build/$lang/doctrees
+      #       sphinx-build -j auto -b html -D language=$lang -d build/$lang/doctrees source dist/$lang
+      #       rm -rf dist/$lang/_sources dist/$lang/_images
+      #     done
+
+      # - name: upload full build artifact
+      #   id: upload-full
+      #   uses: actions/upload-artifact@v4
+      #   with:
+      #     name: generated documentation (all)
+      #     path: dist
+
+      # - name: trigger docs server to download (FULL) artifact
+      #   uses: appleboy/[email protected]
+      #   with:
+      #     host: ${{ secrets.DOCS_HOST }}
+      #     username: docs
+      #     port: ${{ secrets.DOCS_PORT }}
+      #     key: ${{ secrets.DEPLOY_AUTH_KEY }}
+      #     script: /var/www/docs/deploy/github-trigger.sh all ${{ steps.upload-full.outputs.artifact-id }} ${{ secrets.DOWNLOAD_TOKEN }}
+          
+
+ 

.gitignore

@@ -0,0 +1,3 @@
+build
+dist
+venv

Makefile

@@ -0,0 +1,11 @@
+
+
+
+all: venv
+	venv/bin/sphinx-build -j auto -b html -D language=en -d build/en/doctrees source dist/en
+
+
+venv:
+	python -m venv venv
+	venv/bin/pip3 install -r requirements.txt
+

README.md

@@ -0,0 +1,16 @@
+# Nitrokey Documentation
+
+
+
+### Local build
+
+Be sure to have a recent python installed, then:
+
+```
+make
+```
+
+The (english) result is to be found in `dist/en`, to show run:
+```
+firefox dist/en/index.html
+```

requirements.txt

@@ -0,0 +1,31 @@
+alabaster==0.7.13
+Babel==2.12.1
+beautifulsoup4==4.12.2
+certifi==2023.5.7
+charset-normalizer==3.1.0
+docutils==0.18.1
+furo==2023.3.27
+idna==3.4
+imagesize==1.4.1
+Jinja2==3.1.2
+MarkupSafe==2.1.2
+packaging==23.1
+Pygments==2.15.1
+requests==2.30.0
+rstcheck==6.2.0
+snowballstemmer==2.2.0
+soupsieve==2.4.1
+Sphinx==6.2.1
+sphinx-basic-ng==1.0.0b1
+sphinx-copybutton==0.5.2
+sphinx-intl==2.3.0
+sphinx-tabs==3.4.1
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+sphinxprettysearchresults==0.3.5
+urllib3==2.0.2
+setuptools==70.3.0