Merge pull request #4 from brainelectronics/feature/add-docs-and-deta…

…iled-examples

Add docs and detailed examples

.editorconfig

@@ -0,0 +1,27 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# 4 space indentation
+[*.py]
+indent_size = 4
+
+[*.json]
+indent_size = 4
+
+# 2 space indentation
+[*.yml]
+indent_size = 2
+
+[*.{md,rst}]
+indent_size = 4
+trim_trailing_whitespace = false

.flake8

@@ -31,7 +31,7 @@ exclude =
     # There's no value in checking cache directories
     __pycache__,
     # The conf file is mostly autogenerated, ignore it
-    docs/source/conf.py,
+    docs/conf.py,
     # This contains our built documentation
     build,
     # This contains builds that we don't want to check
@@ -44,7 +44,6 @@ exclude =
     libs_external
     sdist_upip.py
     setup.py
-    update_version.py
 
 # Provide a comma-separated list of glob patterns to add to the list of excluded ones.
 # extend-exclude =

.github/workflows/release.yml

@@ -1,5 +1,7 @@
-# this file is *not* meant to cover or endorse the use of GitHub Actions, but rather to
-# help make automated releases for this project
+---
+
+# this file is *not* meant to cover or endorse the use of GitHub Actions, but
+# rather to help make automated releases for this project
 
 name: Upload Python Package
 
@@ -9,35 +11,48 @@ on:
       - main
 
 permissions:
-  contents: read
+  contents: write
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v2
-    - name: Set up Python
-      uses: actions/setup-python@v3
-      with:
-        python-version: '3.9'
-    - name: Install build dependencies
-      run: |
-        if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi
-    - name: Build package
-      run: |
-        changelog2version \
-          --changelog_file changelog.md \
-          --version_file winbond/version.py \
-          --version_file_type py \
-          --debug
-        python setup.py sdist
-        rm dist/*.orig
-      # sdist call create non conform twine files *.orig, remove them
-    - name: Publish package
-      uses: pypa/gh-action-pypi-publish@release/v1.5
-      with:
-        password: ${{ secrets.PYPI_API_TOKEN }}
-        skip_existing: true
-        verbose: true
-        print_hash: true
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '3.9'
+      - name: Install build dependencies
+        run: |
+          if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi
+      - name: Build package
+        run: |
+          changelog2version \
+            --changelog_file changelog.md \
+            --version_file winbond/version.py \
+            --version_file_type py \
+            --debug
+          python setup.py sdist
+          rm dist/*.orig
+        # sdist call create non conform twine files *.orig, remove them
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1.5
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip_existing: true
+          verbose: true
+          print_hash: true
+      - name: 'Create changelog based release'
+        uses: brainelectronics/changelog-based-release@v1
+        with:
+          # note you'll typically need to create a personal access token
+          # with permissions to create releases in the other repo
+          # or you set the "contents" permissions to "write" as in this example
+          changelog-path: changelog.md
+          tag-name-prefix: ''
+          tag-name-extension: ''
+          release-name-prefix: ''
+          release-name-extension: ''
+          draft-release: true
+          prerelease: false

.github/workflows/test-release.yaml

@@ -1,53 +1,69 @@
-# this file is *not* meant to cover or endorse the use of GitHub Actions, but rather to
-# help make automated releases for this project
+---
+
+# this file is *not* meant to cover or endorse the use of GitHub Actions, but
+# rather to help make automated test releases for this project
 
 name: Upload Python Package to test.pypi.org
 
 on: [pull_request]
 
 permissions:
-  contents: read
+  contents: write
 
 jobs:
   test-deploy:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v2
-    - name: Set up Python
-      uses: actions/setup-python@v3
-      with:
-        python-version: '3.9'
-    - name: Install build dependencies
-      run: |
-        if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi
-    - name: Build package
-      run: |
-        changelog2version \
-          --changelog_file changelog.md \
-          --version_file winbond/version.py \
-          --version_file_type py \
-          --additional_version_info="-rc${{ github.run_number }}.dev${{ github.event.number }}" \
-          --debug
-        python setup.py sdist
-    - name: Test built package
-      # sdist call creates non twine conform "*.orig" files, remove them
-      run: |
-        rm dist/*.orig
-        twine check dist/*.tar.gz
-    - name: Archive build package artifact
-      uses: actions/upload-artifact@v3
-      with:
-        # https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
-        # ${{ github.repository }} and ${{ github.ref_name }} can't be used for artifact name due to unallowed '/'
-        name: dist_repo.${{ github.event.repository.name }}_sha.${{ github.sha }}_build.${{ github.run_number }}
-        path: dist/*.tar.gz
-        retention-days: 14
-    - name: Publish package
-      uses: pypa/gh-action-pypi-publish@release/v1.5
-      with:
-        repository_url: https://test.pypi.org/legacy/
-        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
-        skip_existing: true
-        verbose: true
-        print_hash: true
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '3.9'
+      - name: Install build dependencies
+        run: |
+          if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi
+      - name: Build package
+        run: |
+          changelog2version \
+            --changelog_file changelog.md \
+            --version_file winbond/version.py \
+            --version_file_type py \
+            --additional_version_info="-rc${{ github.run_number }}.dev${{ github.event.number }}" \
+            --debug
+          python setup.py sdist
+      - name: Test built package
+        # sdist call creates non twine conform "*.orig" files, remove them
+        run: |
+          rm dist/*.orig
+          twine check dist/*.tar.gz
+      - name: Archive build package artifact
+        uses: actions/upload-artifact@v3
+        with:
+          # https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
+          # ${{ github.repository }} and ${{ github.ref_name }} can't be used
+          # for artifact name due to unallowed '/'
+          name: dist_repo.${{ github.event.repository.name }}_sha.${{ github.sha }}_build.${{ github.run_number }}
+          path: dist/*.tar.gz
+          retention-days: 14
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1.5
+        with:
+          repository_url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          skip_existing: true
+          verbose: true
+          print_hash: true
+      - name: 'Create changelog based prerelease'
+        uses: brainelectronics/changelog-based-release@v1
+        with:
+          # note you'll typically need to create a personal access token
+          # with permissions to create releases in the other repo
+          # or you set the "contents" permissions to "write" as in this example
+          changelog-path: changelog.md
+          tag-name-prefix: ''
+          tag-name-extension: '-rc${{ github.run_number }}.dev${{ github.event.number }}'
+          release-name-prefix: ''
+          release-name-extension: '-rc${{ github.run_number }}.dev${{ github.event.number }}'
+          draft-release: true
+          prerelease: true

.github/workflows/test.yml

@@ -1,5 +1,9 @@
-# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+---
+
+# This workflow will install Python dependencies, run tests and lint with a
+# specific Python version
+# For more information see:
+# https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
 
 name: Test Python package
 
@@ -17,31 +21,34 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v3
-    - name: Set up Python
-      uses: actions/setup-python@v3
-      with:
-        python-version: '3.9'
-    - name: Install test dependencies
-      run: |
-        pip install -r requirements-test.txt
-    - name: Lint with flake8
-      run: |
-        flake8 .
-    - name: Install deploy dependencies
-      run: |
-        python -m pip install --upgrade pip
-        if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi
-    - name: Build package
-      run: |
-        changelog2version \
-          --changelog_file changelog.md \
-          --version_file winbond/version.py \
-          --version_file_type py \
-          --debug
-        python setup.py sdist
-        rm dist/*.orig
-    - name: Test built package
-      run: |
-        twine check dist/*
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '3.9'
+      - name: Install test dependencies
+        run: |
+          pip install -r requirements-test.txt
+      - name: Lint with flake8
+        run: |
+          flake8 .
+      - name: Lint with yamllint
+        run: |
+          yamllint .
+      - name: Install deploy dependencies
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi
+      - name: Build package
+        run: |
+          changelog2version \
+            --changelog_file changelog.md \
+            --version_file winbond/version.py \
+            --version_file_type py \
+            --debug
+          python setup.py sdist
+          rm dist/*.orig
+      - name: Test built package
+        run: |
+          twine check dist/*

.readthedocs.yaml

@@ -0,0 +1,22 @@
+---
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: docs/requirements.txt

.yamllint

@@ -0,0 +1,13 @@
+---
+
+extends: default
+
+ignore:
+  - .tox
+  - .venv
+
+rules:
+  line-length:
+    level: warning
+    ignore:
+      - .github/workflows/*