[#1375] add versioning to python docs (#1397)

* add mike as versioning provider for python docs (#1375) Signed-off-by: bossenti <bossenti@posteo.de> * adapt GitHub workflow for python docs creation (#1375) * add doc releasing to python deployment (#1375) * retrieve release version from branch name (#1375) --------- Signed-off-by: bossenti <bossenti@posteo.de> [#1375] add versioning to python docs (#1397)
apache · Mar 10, 2023 · 9070160 · 9070160
1 parent 1ed7b81
commit 9070160
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 16 deletions.
diff --git a/.github/workflows/pypi-deployment.yml b/.github/workflows/pypi-deployment.yml
@@ -13,9 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: Deploy Python Package to PyPI
+name: Deploy Python Package to PyPI & update docs
 
-on: [workflow_dispatch]
+on:
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -36,6 +37,7 @@ jobs:
           cd ./streampipes-client-python
           python -m pip install --upgrade pip 
           pip install build twine
+          pip install -e ".[docs]"
 
       - name: Build package
         run: |
@@ -47,4 +49,17 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
-          password: ${{ secrets.PYPI_TOKEN }}
+          password: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Publish new doc version and update alias
+        working-directory: ./streampipes-client-python
+        run: |
+          mike deploy ${GITHUB_REF##*/} latest -u --deploy-prefix ./streampipes-client-python/docs-tmp -b ${GITHUB_REF}
+          git reset --hard  # undo local changes that delete generated doc files
+
+      - name: Publish Python docs as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: streampipes-python-docs
+          path: streampipes-client-python/docs-tmp/**/*
+          retention-days: 2
diff --git a/.github/workflows/python-docs.yml b/.github/workflows/python-docs.yml
@@ -0,0 +1,66 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: "build-python-docs-and-share-as-artifact"
+
+on:
+  schedule:
+    - cron:  "0 2 * * 6"  # runs every saturday at 00:00:00
+
+jobs:
+  python-docs-artifact-building:
+    runs-on: ubuntu-latest
+    steps:
+      - name: clone
+        uses: actions/checkout@v3
+
+      - name: create working branch & set GitHub config
+        run: |
+          git checkout -b build-python-docs-${{ github.run_id }}
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.8
+
+      - name: Cache Python dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-doc-${{ hashFiles('**/setup.py') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-doc-
+
+      - name: Install Python dependencies
+        working-directory: ./streampipes-client-python
+        run: |
+          python -m pip install --upgrade pip
+          pip install wheel
+          pip install -e ".[docs]"
+
+      - name: Build Python docs
+        working-directory: ./streampipes-client-python
+        run: |
+          mike deploy dev --deploy-prefix ./streampipes-client-python/docs-tmp -b build-python-docs-${{ github.run_id }}
+          git reset --hard  # undo local changes that delete generated doc files
+
+      - name: Publish Python docs as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: streampipes-python-docs
+          path: streampipes-client-python/docs-tmp/**/*
+          retention-days: 5
diff --git a/streampipes-client-python/mkdocs.yml b/streampipes-client-python/mkdocs.yml
@@ -38,6 +38,9 @@ extra:
     - icon: fontawesome/brands/github-alt
       link: https://github.com/apache/streampipes
 
+  version:
+    provider: mike
+
 # Extensions
 markdown_extensions:
   - admonition
@@ -51,8 +54,8 @@ markdown_extensions:
   - pymdownx.details
   - pymdownx.superfences
   - pymdownx.highlight:
-        use_pygments: true
-        pygments_lang_class: true
+      use_pygments: true
+      pygments_lang_class: true
 
 plugins:
   - awesome-pages
@@ -71,18 +74,24 @@ plugins:
             docstring_section_style: spacy
             show_source: False
             merge_init_into_class: True
+  - mike:
+      canonical_version: 'latest'
+      version_selector: true
+      css_dir: css
+      javascript_dir: js
 
 extra_css:
   - stylesheets/extra.css
 
 nav:
-    - Home: index.md
-    - Getting Started:
-        - Installation: getting-started/installation.md
-        - Quickstart: getting-started/quickstart.md
-    - Examples:
-        - Introduction to the StreamPipes Python Client: examples/1-introduction-to-streampipes-python-client.ipynb
-        - Extracting Data from the StreamPipes Data Lake: examples/2-extracting-data-from-the-streampipes-data-lake.ipynb
-        - Exploring Live Data from a StreamPipes Data Stream: examples/3-getting-live-data-from-the-streampipes-data-stream.ipynb
-        - Applying Online Machine Learning on a StreamPipes Data Stream: examples/4-using-online-machine-learning-on-a-streampipes-data-stream.ipynb
-    - Reference: reference/*
+  - Home: index.md
+  - Getting Started:
+      - First Steps: getting-started/first-steps.md
+      - Developing & Contributing: getting-started/developing.md
+      - Quickstart: getting-started/quickstart.md
+  - Examples:
+      - Introduction to the StreamPipes Python Client: examples/1-introduction-to-streampipes-python-client.ipynb
+      - Extracting Data from the StreamPipes Data Lake: examples/2-extracting-data-from-the-streampipes-data-lake.ipynb
+      - Exploring Live Data from a StreamPipes Data Stream: examples/3-getting-live-data-from-the-streampipes-data-stream.ipynb
+      - Applying Online Machine Learning on a StreamPipes Data Stream: examples/4-using-online-machine-learning-on-a-streampipes-data-stream.ipynb
+  - Reference: reference/*
diff --git a/streampipes-client-python/setup.py b/streampipes-client-python/setup.py
@@ -63,7 +63,8 @@
     "mkdocs-gen-files==0.4.0",
     "mkdocs-literate-nav==0.6.0",
     "numpydoc==1.5.0",
-    "mkdocs-jupyter==0.22.0 "
+    "mkdocs-jupyter==0.22.0",
+    "mike @ git+https://github.com/jimporter/mike.git@872f72def32f588908f8251fe512189e0c41f4e2"
 ]
 
 here = os.path.abspath(os.path.dirname(__file__))