[#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>
apache · Mar 10, 2023 · c530d55 · c530d55
1 parent f505107
commit c530d55
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 19 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:
         run: |
           python -m pip install --upgrade pip 
           pip install build twine
+          pip install -e ".[docs]"
 
       - name: Build package
         working-directory: ./streampipes-client-python
@@ -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
@@ -26,6 +26,12 @@ jobs:
       - 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:
@@ -49,11 +55,12 @@ jobs:
       - name: Build Python docs
         working-directory: ./streampipes-client-python
         run: |
-          make doc
+          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/site/**/*
+          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,19 +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:
-        - 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/*
+  - 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__))