Initial commit

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Describe a problem you're having with the code
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug -**
+1. Include the full Traceback of the error.
+
+**To reproduce -**
+1. Include a simple, standalone code snippet that demonstrates the issue.
+
+**Expected behavior -**
+
+**Your setup -**
+ - code version:
+ - Python version:
+ - Operating system:
+
+**Additional context -**
+(E.g., any peculiarity of the data or of the problem you're trying to solve?)

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Suggest an idea for improving/expanding the code
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe -**
+
+**Describe the solution you'd like -**
+
+**Describe alternatives you've considered -**
+
+**Additional context -**

.github/workflows/docs.yml

@@ -0,0 +1,108 @@
+name: Docs
+
+on:
+  push:
+    branches: 
+      - main
+# when a review is requested on a PR that targets `main`, or the PR is closed:    
+  # pull_request:
+  #   types: [review_requested, closed]
+
+# Prevent multiple PRs from building/deploying the docs at the same time
+concurrency:
+  group: ${{ github.workflow }}
+
+jobs:
+  docs-build:
+    name: Build docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+
+      - name: Install docs dependencies
+        run: |
+          sudo apt-get install pandoc
+          pip install setuptools --upgrade
+          pip install .[test,docs]
+
+      - name: Make docs
+        run: |
+          pip install .
+          cd docs
+          make html
+
+      # check code coverage, store results in the built docs.
+      # coverage.py creates a .gitignore with '*' where it's run; remove it
+      # to keep the coverage report and badge on gh-pages
+      - name: Coverage
+        # only continue if the PR is not just closed, but also merged:
+        # if: github.event.pull_request.merged == true
+        run: |
+          coverage run --source=py_template -m pytest test/*.py
+          coverage report
+          mkdir -p docs/_build/html/coverage
+          coverage html -d docs/_build/html/coverage
+          rm docs/_build/html/coverage/.gitignore
+          coverage-badge -f -o docs/_build/html/coverage/badge.svg
+
+      # upload the built docs as an artifact so the files can be accessed
+      # by a subsequent job in the workflow.
+      # only store the artifact for 'retention-days'
+      - name: Upload docs artifact
+        # if: github.event.pull_request.merged == true
+        uses: actions/upload-artifact@v4
+        with:
+          name: built_docs
+          path: docs/_build/html
+          retention-days: 1
+
+  docs-deploy:
+    name: Deploy docs
+    needs: docs-build
+    # if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions: 
+      contents: write
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      # download the previously uploaded 'built_docs' artifact
+      - name: Download docs artifact
+        uses: actions/download-artifact@v4
+        id: download
+        with:
+          name: built_docs
+          path: docs/_build/html
+
+      - name: Echo download path
+        run: echo ${{steps.download.outputs.download-path}}
+
+      - name: Disable jekyll builds
+        run: touch docs/_build/html/.nojekyll
+
+      - name: Display docs file structure
+        run: ls -aR
+        working-directory: docs/_build/html
+
+      - name: Install and configure dependencies
+        run: |
+          npm install -g --silent gh-pages@2.0.1
+
+      - name: Deploy docs to gh-pages branch
+        run: |
+          git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
+          npx gh-pages --dotfiles --dist docs/_build/html --user "github-actions-bot <support+actions@github.com>" --message "Update docs [skip ci]"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/format_lint.yml

@@ -0,0 +1,33 @@
+name: Coding standards
+on: push
+
+jobs:
+  check_code_standards:
+    name: Format, lint code
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+
+      - name: Install dependencies
+        run: | 
+          pip install setuptools --upgrade
+          pip install .[coding_standards]
+
+      - name: Install package
+        run: pip install .    
+
+      - name: Run `black` formatter
+        run: black .
+
+      - name: Run `ruff` linter / formatter
+        run: ruff check .

.github/workflows/package.yml

@@ -0,0 +1,42 @@
+name: build and release to PyPI
+
+on:
+  release:
+    types:
+      - released
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install setuptools wheel twine
+          pip install pep517 --user
+
+      - name: Install package
+        run: |
+          pip install .
+
+      - name: Build binary wheel and source tarball
+        run: |
+          python -m pep517.build --source --binary --out-dir dist/ .
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}

.github/workflows/tests.yml

@@ -0,0 +1,36 @@
+name: Tests
+on: push
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+
+    steps:
+    - name: Check out code 
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Display Python version
+      run: python -c "import sys; print(sys.version)"
+
+    - name: Install test dependencies        
+      run: |
+        pip install setuptools --upgrade
+        pip install .[test]
+
+    - name: Install package
+      run: pip install .    
+
+    - name: Run unit tests
+      run: |
+        mkdir -p test-reports
+        py.test -v --junitxml=test-reports/junit.xml test/*.py

.github/workflows/type_check.yml

@@ -0,0 +1,32 @@
+name: Type checking
+on: push
+
+jobs:
+  type_check:
+    name: Type check code with mypy
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+
+      - name: Install dependencies
+        run: | 
+          pip install setuptools --upgrade
+          pip install .[type_checking]
+
+      - name: Install package
+        run: pip install .
+
+      - name: Run `mypy` type checker
+        # proceed even if mypy checking fails:
+        continue-on-error: true
+        run: mypy --strict .