From b7179fcb9d86a64e15241233a5a5b3dda4005ce0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ernst=20W=C3=BCrger?= <ernst.wuerger@deutschebahn.com>
Date: Tue, 8 Oct 2024 10:36:17 +0200
Subject: [PATCH] docs: Fix docs (#113)

---
 .github/workflows/docs.yml                      |  16 ++++++++++++++--
 .github/workflows/lint.yml                      |  10 +++++-----
 .pre-commit-config.yaml                         |   7 ++++---
 .../source/_static/{c2p-uc1.GIF => c2p-uc1.gif} | Bin
 ...{c2p-uc1.GIF.license => c2p-uc1.gif.license} |   0
 docs/source/pipeline templates/gitlab.rst       |   6 +++---
 6 files changed, 26 insertions(+), 13 deletions(-)
 rename docs/source/_static/{c2p-uc1.GIF => c2p-uc1.gif} (100%)
 rename docs/source/_static/{c2p-uc1.GIF.license => c2p-uc1.gif.license} (100%)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index df553490..77bb53fa 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -4,8 +4,10 @@
 name: Docs
 
 on:
+  pull_request:
   push:
     branches: ["main"]
+  workflow_dispatch:
 
 jobs:
   sphinx:
@@ -18,6 +20,8 @@ jobs:
           fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
+          cache: pip
+          cache-dependency-path: pyproject.toml
           python-version: "3.12"
       - name: Upgrade pip
         run: |
@@ -26,8 +30,16 @@ jobs:
         run: |
           python -m pip install '.[docs]'
       - name: Create docs
-        run: |
-          make -C docs html
+        env:
+          SPHINXOPTS: ${{ github.ref != 'refs/heads/master' && '-W' || '' }}
+        run: make -C docs html
+      - name: Upload built docs as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: Documentation
+          path: docs/build/html
+          if-no-files-found: error
+          retention-days: 5
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 3dc16a8f..a56d233b 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -11,8 +11,8 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
       - name: Upgrade pip
@@ -20,15 +20,15 @@ jobs:
           python -m pip install -U pip
       - name: Install pre-commit
         run: |-
-          python -m pip install pre-commit types-docutils
+          python -m pip install 'pre-commit<4.0.0' types-docutils
       - name: Run Pre-Commit
         run: |-
           pre-commit run --all-files
   pylint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
       - name: Upgrade pip
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c533a221..0934cde3 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -2,10 +2,11 @@
 # SPDX-License-Identifier: CC0-1.0
 
 default_install_hook_types: [commit-msg, pre-commit]
-default_stages: [commit, merge-commit]
+default_stages: [pre-commit, pre-merge-commit]
+minimum_pre_commit_version: 3.2.0
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-added-large-files
       - id: check-ast
@@ -26,7 +27,7 @@ repos:
       - id: fix-byte-order-marker
       - id: trailing-whitespace
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.8.0
+    rev: 24.10.0
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/isort
diff --git a/docs/source/_static/c2p-uc1.GIF b/docs/source/_static/c2p-uc1.gif
similarity index 100%
rename from docs/source/_static/c2p-uc1.GIF
rename to docs/source/_static/c2p-uc1.gif
diff --git a/docs/source/_static/c2p-uc1.GIF.license b/docs/source/_static/c2p-uc1.gif.license
similarity index 100%
rename from docs/source/_static/c2p-uc1.GIF.license
rename to docs/source/_static/c2p-uc1.gif.license
diff --git a/docs/source/pipeline templates/gitlab.rst b/docs/source/pipeline templates/gitlab.rst
index fb9f6b21..fe604346 100644
--- a/docs/source/pipeline templates/gitlab.rst	
+++ b/docs/source/pipeline templates/gitlab.rst	
@@ -14,7 +14,7 @@ following template can be used inside the `.gitlab-ci.yml` file:
 
 We highly recommend using the diagram cache as a separate job and defined it as a dependency in our template for that
 reason. The diagram cache artifacts have to be included in the capella2polarion job and its path must be defined in the
-`CAPELLA2POLARION_MODEL_JSON` variable. A `.gitlab-ci.yml` with a capella2polarion synchronization job could look like
+`CAPELLA2POLARION_CAPELLA_MODEL` variable. A `.gitlab-ci.yml` with a capella2polarion synchronization job could look like
 this:
 
 .. code:: yaml
@@ -35,6 +35,6 @@ this:
         CAPELLA_VERSION: 6.1.0
         ENTRYPOINT: model.aird
         CAPELLA2POLARION_PROJECT_ID: syncproj
-        CAPELLA2POLARION_MODEL_JSON: '{"path": "PATH_TO_CAPELLA", "diagram_cache": "./diagram_cache"}'
-        CAPELLA2POLARION_CONFIG: capella2polarion_config.yaml
+        CAPELLA2POLARION_CAPELLA_MODEL: '{"path": "PATH_TO_CAPELLA", "diagram_cache": "./diagram_cache"}'
+        CAPELLA2POLARION_SYNCHRONIZE_CONFIG: capella2polarion_config.yaml
         CAPELLA2POLARION_DEBUG: 1