🚀📄Deploy Documentation to GitHub Pages - instead of RTD

.github/workflows/docs_latest.yml

@@ -0,0 +1,50 @@
+name: Build documentation /latest
+
+on:
+  push:
+    branches: [main]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: 🚀📄 Build and deploy documentation to GitHub Pages
+    # This setup is inspired by
+    # https://github.com/KernelTuner/kernel_tuner/blob/master/.github/workflows/docs-on-release.yml
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+        # Note: The sphinx action below can only install a single requirements file.
+      - name: Write version to conf.py
+        run: |
+          echo -e "version = release = \"latest\"\n" | cat - docs/conf.py > /tmp/conf.py && mv /tmp/conf.py docs/conf.py
+      - name: Build the documentation
+        uses: sphinx-notes/pages@v2
+        # Note: This action has a newer version (v3 atm), but it doesn't has the feature to specify the target path.
+        # We need that in order to be able to store (and deploy) multiple versions of the documentation.
+        with:
+          requirements_path: docs/requirements.txt
+          documentation_path: docs/
+          target_path: latest/
+          target_branch: gh-pages
+          sphinx_options: -W -j auto
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages

.github/workflows/python-publish.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Run the Tests
         run: |
           tox -e tests
-  generate:
+  json_schemas:
     name: Generate JSON-Schemas
     runs-on: ubuntu-latest
     needs: tests
@@ -70,6 +70,58 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.BO4E_PYTHON_GENERATE_SCHEMAS }} # this token expires on 2024-10-09
           VERSION: ${{ github.ref_name }}
+  docs:
+    name: 🚀📄 Build and deploy documentation to GitHub Pages
+    # This setup is inspired by
+    # https://github.com/KernelTuner/kernel_tuner/blob/master/.github/workflows/docs-on-release.yml
+    runs-on: ubuntu-latest
+    needs: tests
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # otherwise, you will fail to push refs to dest repo
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+        # Note: The sphinx action below can only install a single requirements file.
+      - name: Write version to conf.py
+        run: |
+          echo -e "version = release = \"${{ github.ref_name }}\"\n" | cat - docs/conf.py > /tmp/conf.py
+          mv /tmp/conf.py docs/conf.py
+      - name: Build the documentation
+        uses: sphinx-notes/pages@v2
+        # Note: This action has a newer version (v3 atm), but it doesn't has the feature to specify the target path.
+        # We need that in order to be able to store (and deploy) multiple versions of the documentation.
+        with:
+          requirements_path: docs/requirements.txt
+          documentation_path: docs/
+          target_path: ${{ github.ref_name }}
+          target_branch: gh-pages
+          sphinx_options: -W -j auto
+      - id: latest_bo4e
+        name: Get latest BO4E release tag
+        uses: pozetroninc/github-action-get-latest-release@master
+        with:
+          repository: ${{ github.repository }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Redirect stable to new release if the new release is marked as latest
+        if: steps.latest_bo4e.outputs.release == github.ref_name
+        run: |
+          echo "Redirecting stable to new version ${{ github.ref_name }}"
+          rm -rf stable
+          ln -s ${{ github.ref_name }} stable
+          git add stable
+          git commit -m "Redirect stable to new version ${{ github.ref_name }}"
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+            github_token: ${{ secrets.GITHUB_TOKEN }}
+            branch: gh-pages
   build-n-publish:
     name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
     runs-on: ubuntu-latest
@@ -78,7 +130,7 @@ jobs:
     permissions:
       # IMPORTANT: this permission is mandatory for trusted publishing
       id-token: write
-    needs: [tests, generate]
+    needs: [tests, json_schemas, docs]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python

.github/workflows/test_docs.yml

@@ -0,0 +1,23 @@
+name: "Test Doc Creation (Sphinx)"
+on: [pull_request]
+jobs:
+  docbuild:
+    name: Check Docs
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+      - name: Check Docs
+        run: |
+          tox -e docs

docs/conf.py

@@ -97,15 +97,6 @@
 project = "bo4e"
 copyright = "2022, Hochfrequenz GmbH"
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = ""  # Is set by calling `setup.py docs`
-# The full version, including alpha/beta/rc tags.
-release = ""  # Is set by calling `setup.py docs`
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 # language = None
@@ -176,8 +167,12 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-from bo4e import __gh_version__ as release
-from bo4e import __version__ as version
+# Note: For the deployment to GitHub Pages the release and version values will
+# be set by the action. This is to support things like /latest or /stable.
+if "release" not in globals():
+    from bo4e import __gh_version__ as release
+if "version" not in globals():
+    from bo4e import __version__ as version
 
 print(f"Got version = {version} from __version__")
 print(f"Got release = {release} from __gh_version__")
@@ -309,7 +304,7 @@
 
 # Create UML diagrams in plantuml format. Compile these into svg files into the _static folder.
 # See docs/uml.py for more details.
-uml.LINK_URI_BASE = f"https://bo4e-python.readthedocs.io/en/{release}"
+uml.LINK_URI_BASE = f"https://bo4e.github.io/BO4E-python/{release}"
 _exec_plantuml = Path(__location__) / "plantuml.jar"
 _network, _namespaces_to_parse = uml.build_network(Path(module_dir), uml.PlantUMLNetwork)
 print(_network)

docs/uml.py

@@ -79,11 +79,8 @@ def __init__(self, *, scope: Optional[List[str]] = None, color: Optional[str] =
 #: Define shorthand for Cardinality type since none of the values have to be provided.
 Cardinality = tuple[str, str]
 
-#: Define the link base URI used in svg links
-LINK_URI_BASE = "https://bo4e-python.readthedocs.io/en/latest"
-
-# link domain to test links only local.
-# LINK_URI_BASE = f"file:///{Path.cwd().parent}/.tox/docs/tmp/html"
+#: Define the link base URI used in svg links. Will be overridden by conf.py.
+LINK_URI_BASE = f"file:///{Path(__file__).parents[1]}/.tox/docs/tmp/html"
 
 
 class _UMLNetworkABC(nx.MultiDiGraph, metaclass=ABCMeta):