38: Publish documentation for releases to GitHub pages (#39)

* Use  sphinx-github-pages-generator for publishing documentation to GitHub pages
* Add github workflow to deploy GitHub pages at push to main branch and release
* Introduce nox for build tasks

Co-authored-by: MarleneKress79789 <marlene.kress@gmx.de>
Co-authored-by: Torsten Kilias <tkilias@users.noreply.github.com>
Co-authored-by: Nicola Coretti  <nico.coretti@gmail.com>

Author: 3 people

.github/workflows/check_github_pages_docs_for_feature_branch.yaml renamed to .github/workflows/check_documentation_build.yaml

@@ -1,10 +1,12 @@
-name: Check documentation build and deployment for feature branch
+name: Check the documentation build, publish if on main
 
 on:
   push:
+ # Only trigger if branches get pushed (ignored pushed a tag)
+    tags-ignore:
+      - '**'
     branches-ignore:
-      - main
-      - github-pages/*
+    - github-pages/*
 
 jobs:
   create_github_pages_docs:
@@ -27,12 +29,12 @@ jobs:
         poetry-version: 1.1.11
     - name: Poetry install
       run: poetry install
-    - name: Test documentation deployment for current feature branch
+    - name: Deploy documentation to github-pages branch
       run: |
         git config --local user.email "opensource@exasol.com"
         git config --local user.name "GitHub Action"
         git fetch
-        SOURCE_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
-        TARGET_BRANCH="$(doc/get_target_branch_name.sh "$SOURCE_BRANCH")"
-        poetry run poe push-html-doc-to-github-pages-current || echo
-        git push origin --delete "$TARGET_BRANCH"
+        poetry run python -m nox -s push-pages-current
+    - name: Cleanup delete target branch
+      if: ${{ !contains(github.ref, 'main') }}
+      run: git push -d origin "github-pages/"$(git branch --show-current)""

.github/workflows/deploy_github_pages_docs_for_main.yaml renamed to .github/workflows/create_release_docu.yaml

@@ -1,33 +1,34 @@
-name: Build and push documentation for main branch
+name: Generate release documentation
 
 on:
-  push:
-    branches:
-      - main
+  release:
+    types: [published]
 jobs:
-  create_github_pages_docs:
+
+  publish-release-documentation:
     strategy:
       fail-fast: false
-      matrix:
-        python-version: [3.8]
     runs-on: ubuntu-latest
 
+    environment: publish
+
     steps:
     - name: Checkout
       uses: actions/checkout@v2
     - name: Install python
       uses: actions/setup-python@v2
       with:
-        python-version: ${{ matrix.python-version }}
+        python-version: 3.8
     - name: Install poetry
       uses: abatilo/actions-poetry@v2.1.4
       with:
         poetry-version: 1.1.11
     - name: Poetry install
       run: poetry install
-    - name: Deploy documentation to github-pages-main branch
+    - name: Deploy release documentation to github-pages branch
       run: |
         git config --local user.email "opensource@exasol.com"
         git config --local user.name "GitHub Action"
         git fetch
-        poetry run poe push-html-doc-to-github-pages-main
+        poetry run python -m nox -s push-pages-release
+

.gitignore

@@ -136,6 +136,7 @@ poetry.lock
 
 # Sphinx
 doc/_build
+doc/.build-docu
 doc/api
 
 # Language container

README.rst

@@ -31,7 +31,8 @@ Or install the wheel directly via::
 Documentation
 -------------
 
-`Documentation for the latest release <https://exasol.github.io/bucketfs-utils-python/main>`_ is hosted on the Github Pages of this project.
+`Documentation for the current main branch <https://exasol.github.io/bucketfs-utils-python/main>`_ is hosted on the Github Pages of this project.
+`Here <https://exasol.github.io/bucketfs-utils-python>`_  is a list of documentations for previous releases.
 
 Features
 ========

doc/Makefile

@@ -15,6 +15,7 @@
 ## Refactoring
 
  - #53: Upgraded Python version to >=3.8, removed numpy from source again
+ - #38: Replaced old bash scripts for building documentation with Sphinx_Github-Pages-generator, migrated to Nox
 
 ## Security
 

doc/changes/changes_0.3.0.md

@@ -10,9 +10,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
+import os
+import sys
 # sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../'))
 
 
 # -- Project information -----------------------------------------------------
@@ -52,15 +53,15 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.build-docu']
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'furo'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,