#29: Use sphinx for documentation

.github/workflows/check_github_pages_docs_for_feature_branch.yaml

@@ -0,0 +1,38 @@
+name: Check documentation build and deployment for feature branch
+
+on:
+  push:
+    branches-ignore:
+      - main
+      - github-pages/*
+
+jobs:
+  create_github_pages_docs:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [3.6]
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+    - name: Install python
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install poetry
+      uses: abatilo/actions-poetry@v2.0.0
+      with:
+        poetry-version: 1.1.4
+    - name: Poetry install
+      run: poetry install
+    - name: Test documentation deployment for current feature 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"

.github/workflows/check_setup_py.yaml

@@ -1,6 +1,9 @@
 name: Check if setup.py is up to date
 
-on: [push, pull_request]
+on:
+  push:
+    branches-ignore:
+      - github-pages/*
 
 jobs:
   check_setup_py:
@@ -16,6 +19,10 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
     - uses: abatilo/actions-poetry@v2.0.0
+      with:
+        poetry-version: 1.1.4
+    - name: Poetry install
+      run: poetry install
     - name: Run packaging update
       run: bash githooks/update_setup_py.sh
     - name: Show changes on working copy

.github/workflows/deploy_github_pages_docs_for_main.yaml

@@ -0,0 +1,33 @@
+name: Build and push documentation for main branch
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  create_github_pages_docs:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [3.6]
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+    - name: Install python
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install poetry
+      uses: abatilo/actions-poetry@v2.0.0
+      with:
+        poetry-version: 1.1.4
+    - name: Poetry install
+      run: poetry install
+    - name: Deploy documentation to github-pages-main 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

.github/workflows/pytest.yaml

@@ -1,6 +1,9 @@
 name: Run pytest tests
 
-on: [ push, pull_request ]
+on:
+  push:
+    branches-ignore:
+      - github-pages/*
 
 jobs:
   integration_tests:
@@ -16,6 +19,8 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - uses: abatilo/actions-poetry@v2.0.0
+        with:
+          poetry-version: 1.1.4
       - name: Poetry install
         run: poetry install
       - name: Poetry build

.gitignore

@@ -132,4 +132,7 @@ dmypy.json
 poetry.lock
 
 # PyCharm
-.idea
+.idea
+
+# Sphinx
+doc/_build

README.rst

@@ -0,0 +1,43 @@
+#####################
+BucketFS Utils Python
+#####################
+
+********
+Overview
+********
+
+This project provides a python library for accessing the Exasol BucketFS system.
+It provides functions to upload and download files to and from the BucketFS.
+
+In a Nutshell
+=============
+
+Prerequisites
+-------------
+
+- Python 3.6+
+
+Installation
+-------------
+
+Install the package from Github via `pip`::
+
+    pip install -e git://github.com/exasol/bucketfs-utils-python.git@{tag name}#egg=exasol-bucketfs-utils-python
+
+Documentation
+-------------
+
+`Documentation for the latest release text <https://exasol.github.io/bucketfs-utils-python/>`_ is hosted on the Github Pages of this project.
+
+Features
+========
+
+* Download or upload files from/to the Exasol BucketFS
+* Supported sources and targets for the uploads and downloads:
+
+  * Files on the local Filesystem
+  * Python file objects
+  * Python Strings
+  * Python objects ((De-)Serialization with [Joblib](https://joblib.readthedocs.io/en/latest/persistence.html))
+
+* Loading an artefact from a public Github Release into the BucketFS

doc/Makefile

@@ -0,0 +1,30 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SPHINXAPIDOC        ?= sphinx-apidoc 
+SOURCEDIR     = .
+BUILDDIR      = _build
+MODULES_PATH  = ../exasol_bucketfs_utils_python
+APIDOC_OUTPUT  = api
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+api-doc:
+	@$(SPHINXAPIDOC) -T -d 1 --separate -o "$(APIDOC_OUTPUT)" "$(MODULES_PATH)"
+
+clean-build:
+	[ ! -e "$(BUILDDIR)" ] || rm -r "$(BUILDDIR)"
+	[ ! -e "$(APIDOC_OUTPUT)" ] || rm -r "$(APIDOC_OUTPUT)"
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile api-doc
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/api/exasol_bucketfs_utils_python.bucket_config.rst

@@ -0,0 +1,7 @@
+exasol\_bucketfs\_utils\_python.bucket\_config module
+=====================================================
+
+.. automodule:: exasol_bucketfs_utils_python.bucket_config
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/exasol_bucketfs_utils_python.bucketfs_config.rst

@@ -0,0 +1,7 @@
+exasol\_bucketfs\_utils\_python.bucketfs\_config module
+=======================================================
+
+.. automodule:: exasol_bucketfs_utils_python.bucketfs_config
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/exasol_bucketfs_utils_python.bucketfs_connection_config.rst

@@ -0,0 +1,7 @@
+exasol\_bucketfs\_utils\_python.bucketfs\_connection\_config module
+===================================================================
+
+.. automodule:: exasol_bucketfs_utils_python.bucketfs_connection_config
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/exasol_bucketfs_utils_python.bucketfs_utils.rst

@@ -0,0 +1,7 @@
+exasol\_bucketfs\_utils\_python.bucketfs\_utils module
+======================================================
+
+.. automodule:: exasol_bucketfs_utils_python.bucketfs_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/exasol_bucketfs_utils_python.download.rst

@@ -0,0 +1,7 @@
+exasol\_bucketfs\_utils\_python.download module
+===============================================
+
+.. automodule:: exasol_bucketfs_utils_python.download
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/exasol_bucketfs_utils_python.github_release_file_bucketfs_uploader.rst

@@ -0,0 +1,7 @@
+exasol\_bucketfs\_utils\_python.github\_release\_file\_bucketfs\_uploader module
+================================================================================
+
+.. automodule:: exasol_bucketfs_utils_python.github_release_file_bucketfs_uploader
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/exasol_bucketfs_utils_python.release_link_extractor.rst

@@ -0,0 +1,7 @@
+exasol\_bucketfs\_utils\_python.release\_link\_extractor module
+===============================================================
+
+.. automodule:: exasol_bucketfs_utils_python.release_link_extractor
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/exasol_bucketfs_utils_python.rst

@@ -0,0 +1,25 @@
+exasol\_bucketfs\_utils\_python package
+=======================================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   exasol_bucketfs_utils_python.bucket_config
+   exasol_bucketfs_utils_python.bucketfs_config
+   exasol_bucketfs_utils_python.bucketfs_connection_config
+   exasol_bucketfs_utils_python.bucketfs_utils
+   exasol_bucketfs_utils_python.download
+   exasol_bucketfs_utils_python.github_release_file_bucketfs_uploader
+   exasol_bucketfs_utils_python.release_link_extractor
+   exasol_bucketfs_utils_python.upload
+
+Module contents
+---------------
+
+.. automodule:: exasol_bucketfs_utils_python
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/exasol_bucketfs_utils_python.upload.rst

@@ -0,0 +1,7 @@
+exasol\_bucketfs\_utils\_python.upload module
+=============================================
+
+.. automodule:: exasol_bucketfs_utils_python.upload
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/changes/changelog.rst

@@ -0,0 +1,8 @@
+*****************
+Changelog
+*****************
+
+.. toctree::
+   :maxdepth: 1
+
+   changes_0.1.0.md

doc/changes/changes_0.1.0.md

@@ -1,7 +1,15 @@
-# BucketFS Utils Python 0.1.0, released 2020-11-??
-
+# BucketFs Utily Python 0.1.0, released XYZ
 Code name: Initial implementation
 
-## Features
+## Summary
+
+### Features
+
+  - #1: Added initial implementation.
+  - #6: Download file into fileobj, string or file
+  - #7: Upload file, string or fileboj
+  - #29: Add sphinx documentation
+
+### Refactorings
 
-#1: Added initial implementation.
+  - #15: Remove DepHell dependency, because it is not maintained anymore