docs: Install pandoc github action

.github/workflows/docs.yml

@@ -1,39 +1,51 @@
-# Copyright DB InfraGO AG and contributors
+# SPDX-FileCopyrightText: Copyright DB InfraGO AG
 # SPDX-License-Identifier: CC0-1.0
 
 name: Docs
 
 on:
-  push:
-    branches: ["master"]
+    workflow_dispatch:
+    push:
+        branches: [master]
 
 jobs:
-  sphinx:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v2
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-python@v2
-        with:
-          python-version: "3.10"
-      - name: Upgrade pip
-        run: |
-          python -m pip install -U pip
-      - name: Install dependencies
-        run: |
-          python -m pip install '.[docs]'
-      - name: Auto-generate APIDOC sources
-        run: |-
-          sphinx-apidoc --output-dir docs/source/code --force .
-      - name: Create docs
-        run: |
-          make -C docs html
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          force_orphan: true
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/build/html
+    sphinx:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+        steps:
+            - uses: actions/checkout@v3
+              with:
+                  fetch-depth: 0
+            - uses: actions/setup-python@v4
+              with:
+                  cache: pip
+                  cache-dependency-path: pyproject.toml
+                  python-version: "3.12"
+            - name: Upgrade pip
+              run: python -m pip install -U pip
+            - name: Install dependencies
+              run: |
+                  sudo apt-get install -y pandoc
+                  python -m pip install '.[docs]'
+            - name: Auto-generate APIDOC sources
+              run: make -C docs apidoc
+            - name: Create docs
+              run: make -C docs html
+            - name: Archive the docs
+              # https://github.com/actions/upload-artifact#too-many-uploads-resulting-in-429-responses
+              run: (cd docs/build/html && zip -Xr ../html.zip .)
+            - name: Upload built docs as artifact
+              uses: actions/upload-artifact@v3
+              with:
+                  name: Documentation
+                  path: docs/build/html.zip
+                  if-no-files-found: error
+                  retention-days: 5
+            - name: Deploy
+              if: github.ref == 'refs/heads/master'
+              uses: peaceiris/actions-gh-pages@v3
+              with:
+                  force_orphan: true
+                  github_token: ${{ secrets.GITHUB_TOKEN }}
+                  publish_dir: ./docs/build/html