From 90701600cc4dd8f8115d78cc3b764df2371774f7 Mon Sep 17 00:00:00 2001 From: bossenti Date: Fri, 10 Mar 2023 20:44:03 +0100 Subject: [PATCH] [#1375] add versioning to python docs (#1397) * add mike as versioning provider for python docs (#1375) Signed-off-by: bossenti * 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 [#1375] add versioning to python docs (#1397) --- .github/workflows/pypi-deployment.yml | 21 +++++++-- .github/workflows/python-docs.yml | 66 +++++++++++++++++++++++++++ streampipes-client-python/mkdocs.yml | 33 +++++++++----- streampipes-client-python/setup.py | 3 +- 4 files changed, 107 insertions(+), 16 deletions(-) create mode 100644 .github/workflows/python-docs.yml diff --git a/.github/workflows/pypi-deployment.yml b/.github/workflows/pypi-deployment.yml index 9703d426c0..fff44dadaa 100644 --- 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 }} \ No newline at end of file + 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 \ No newline at end of file diff --git a/.github/workflows/python-docs.yml b/.github/workflows/python-docs.yml new file mode 100644 index 0000000000..9717c921ff --- /dev/null +++ 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 index edc04206a1..373d76c863 100644 --- 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 index 1a4e56cd5a..5463bcd118 100644 --- 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__))