properly validate docs during PRs by enabling mkdocs strict mode and updating some plugin

On-behalf-of: @SAP [email protected]

Author: xrstf

.github/workflows/docs-gen-and-push.yaml

@@ -1,4 +1,4 @@
-name: Generate and push docs
+name: Documentation
 
 on:
   # So we can trigger manually if needed
@@ -24,7 +24,7 @@ concurrency:
 
 jobs:
   generate-and-push:
-    name: Generate and push docs
+    name: Generate and push
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # tag=v4.2.2
@@ -42,4 +42,10 @@ jobs:
           python-version: '3.10'
           cache: 'pip'
 
+      # mike does not support giving CLI flags for mkdocs, but we also do not
+      # want to permanently enable strict mode, so here we enable it just for this
+      # task
+      - run: |
+          echo "strict: true" >> docs/mkdocs.yml
+
       - run: make generate-api-docs deploy-docs

docs/requirements.txt

@@ -1,7 +1,7 @@
 mike==2.1.3
 mkdocs==1.5.3
 mkdocs-awesome-pages-plugin==2.9.2
-mkdocs-macros-plugin==1.0.5
+mkdocs-macros-plugin==1.3.7
 mkdocs-material==9.5.17
 mkdocs-material-extensions==1.3.1
 mkdocs-static-i18n==1.2.2

docs/scripts/deploy-docs.sh

@@ -14,10 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-set -o errexit
-set -o nounset
-set -o pipefail
-set -o xtrace
+set -euo pipefail
 
 REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
 cd "$REPO_ROOT/docs"