Merge pull request #48 from cirKITers/cx

Cx
cirKITers · Sep 30, 2024 · af4c7c1 · af4c7c1
2 parents d0cbfe7 + 8ca5ecb
commit af4c7c1
Show file tree

Hide file tree

Showing 15 changed files with 465 additions and 77 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,13 +1,42 @@
 name: Documentation
 on:
-  push:
-    branches:
-      - main
+  pull_request:
+    branches: [ "main" ]
+  workflow_call:
+    inputs:
+      test-run-id:
+        required: true
+        type: string
 permissions:
   contents: write
 jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.ref != 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install poetry
+        run: pipx install poetry
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: 'poetry'
+      - name: Install dependencies
+        run: poetry install --with docs
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - name: Setting up Cache
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .ci-cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Build Docs
+        run: poetry run mkdocs build
   deploy:
     runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
     steps:
       - uses: actions/checkout@v4
       - name: Configure Git Credentials
@@ -20,16 +49,22 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-          cache: 'poetry' # caching pip dependencies
+          cache: 'poetry'
       - name: Install dependencies
         run: poetry install --with docs
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - name: Setting up Cache
         uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .ci-cache
           restore-keys: |
             mkdocs-material-
+      - name: Download a single artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-report
+          run-id: ${{ inputs.test-run-id }}
+          path: docs/coverage/
       - name: Deploy
         run: poetry run mkdocs gh-deploy --force
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,57 @@
+name: Publish
+on:
+  push:
+    branches: [ "main" ]
+permissions:
+  contents: write
+jobs:
+  test:
+    name: Trigger Tests
+    uses: ./.github/workflows/test.yml
+  quality:
+    name: Trigger Quality
+    uses: ./.github/workflows/quality.yml
+  documentation:
+    needs: test
+    name: Trigger Documentation
+    uses: ./.github/workflows/docs.yml
+    with:
+      test-run-id: ${{ github.run_id }}
+  release:
+    needs: [test, quality, documentation]
+    name: Release
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install poetry
+      run: pipx install poetry
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+        cache: 'poetry'
+    - name: Compare tag and version
+      run: |
+        if [ "$(git tag)" = "$(poetry version --short)" ]; then
+          echo "The tag and the version are the same, nothing to do."
+          echo "DORELEASE=false" >> $GITHUB_ENV
+        else
+          echo "DORELEASE=true" >> $GITHUB_ENV
+        fi
+    - name: Create Release & Tag
+      if: env.DORELEASE == 'true'
+      run: |
+        gh release create "$(poetry version --short)" \
+        --repo="$GITHUB_REPOSITORY" \
+        --title="${GITHUB_REPOSITORY#*/} $(poetry version --short)" \
+        --generate-notes
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    - name: Publish to PyPI
+      if: env.DORELEASE == 'true'
+      run: |
+        poetry install --with dev
+        poetry config pypi-token.pypi ${{ secrets.PYPI_API_TOKEN }}
+        poetry build
+        poetry publish
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
@@ -1,13 +1,12 @@
 name: Quality
 on:
-  push:
-    branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  workflow_call:
 permissions:
   contents: read
 jobs:
-  build:
+  quality:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
@@ -17,10 +16,12 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: "3.11"
-        cache: 'poetry' # caching pip dependencies
+        cache: 'poetry'
     - name: Install dependencies
       run: poetry install --with dev
     - name: Lint with flake8
       run: |
         poetry run flake8 qml_essentials
         poetry run flake8 tests
+    - name: Running license check
+      run: poetry run licensecheck --zero --license mit
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -1,26 +1,38 @@
 name: Testing
 on:
-  push:
-    branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  workflow_call:
 permissions:
-  contents: read
+  contents: write
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     steps:
+    # - name: Install Act dependencies
+    #   if: ${{ env.ACT }}
+    #   run: |
+    #     apt update -qq > /dev/null
+    #     apt install apt-utils -y -qq > /dev/null
+    #     apt remove python3
+    #     apt install python3.11 python3-venv pipx -y
     - uses: actions/checkout@v4
     - name: Install poetry
       run: pipx install poetry
     - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
         python-version: "3.11"
-        cache: 'poetry' # caching pip dependencies
+        cache: 'poetry'
     - name: Install dependencies
       run: poetry install --with dev
     - name: Test with pytest
       run: |
         poetry run coverage run -m pytest
         poetry run coverage report -m
+        poetry run coverage html
+    - name: Share coverage report
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-report
+        path: htmlcov/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to QUAFEL
+# Contributing to QML-Essentials
 
 :tada: Welcome! :tada:
 
@@ -7,7 +7,7 @@ Start of by..
 1. Creating an issue using one of the templates (Bug Report, Feature Request)
    - let's discuss what's going wrong or what should be added
    - can you contribute with code? Great! Go ahead! :rocket:
-2. Forking the repository and working on your stuff
+2. Forking the repository and working on your stuff. See the sections below for details on how to set things up.
 3. Creating a pull request to the main repository
 
 ## Setup
@@ -24,23 +24,27 @@ poetry run pre-commit autoupdate
 poetry run pre-commit install
 ```
 
+Currently the only purpose of the hook is to run Black on commit which will do some code formatting for you.
+However be aware, that this might reject your commit and you have to re-do the commit.
+
 ## Testing
 
 We do our testing with Pytest. Corresponding tests can be triggered as follows:
 ```
 poetry run pytest
 ```
+There are Github action pipelines in place, that will do linting and testing once you open a pull request.
+However, it's a good idea to run tests and linting (either Black or Flake8) locally before pushing.
 
 ## Packaging
 
-Building and packaging requires some extra steps (assuming Poetry):
-- `poetry run devpi use https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org`
-- `poetry run devpi login alice --password=456`
-- `poetry run devpi use alice/quantum`
-- `poetry config repositories.quantum https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum`
-- `poetry config http-basic.quantum alice 456` (or remove password for interactive prompt)
-- `poetry version (major|minor|patch|premajor|preminor|prepatch)` as explained [here](https://python-poetry.org/docs/cli/#version)
-- `poetry publish --build -r quantum`
+Packaging is done automagically using Github actions.
+This action is triggered when a new version is being detected in the `pyprojec.toml` file.
+This works by comparing the output of `poetry version --short` against `git tag` and triggering the publishing process if those differ.
+Publishing includes
+- setting the git tag equal to the version specified in `pyproject.toml`
+- creating a release with the current git tag and automatically generated release notes
+- publishing the package to PyPI using the stored credentials
 
 ## Re-Installing Package
 
@@ -62,7 +66,5 @@ poetry run mkdocs serve
 This will automatically trigger a rebuild each time you make changes.
 See the [MkDocs Documentation](https://cirkiters.github.io/qml-essentials/usage/) for more details.
 
-For pushing to Github pages:
-```
-poetry run mkdocs gh-deploy
-```
+Publishing (and building) the documentation is done automagically using Github actions.
+This action is triggered when a new release is made.
diff --git a/README.md b/README.md
@@ -1,16 +1,25 @@
 # QML Essentials
 
-[![version](https://img.shields.io/badge/version-0.1.12-green.svg)](https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/) [![Pipx Status](https://servers.stroblme.de/api/badge/3/uptime/72?color=%2331c754&labelColor=%233f4850)](https://servers.stroblme.de/status/open) [![Quality](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml) [![Testing](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml) [![Documentation](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml)
+[![version](https://img.shields.io/badge/version-0.1.12-green.svg)](https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/) [![Quality](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml) [![Testing](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml) [![Documentation](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml)
 
-## :scroll: About
+## 📜 About
 
 This repo contains some of the commonly used Ansaetze and coding stuff required for working with QML and Data-Reuploading models.
 There are also dedicated classes to calculate entanglement and expressiblity of a provided model as well as its Fourier coefficients.
 
-## :rocket: Getting Started
+## 🚀 Getting Started
 
-You can find installation instructions and documentation on the corresponding [Github Page](https://cirkiters.github.io/qml-essentials/).
+```
+pip install qml-essentials
+```
+or
+```
+poetry add qml-essentials
+```
 
-## :construction: Contributing
+To install our package from [PyPI](https://pypi.org/project/qml-essentials/).
+You can find details on how to use it and further documentation on the corresponding [Github Page](https://cirkiters.github.io/qml-essentials/).
+
+## 🚧 Contributing
 
 Contributions are very welcome! See [Contribution Guidelines](https://github.com/cirKITers/qml-essentials/blob/main/CONTRIBUTING.md).
diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,10 @@
-[![Pipx Status](https://servers.stroblme.de/api/badge/3/uptime/72?color=%2331c754&labelColor=%233f4850)](https://servers.stroblme.de/status/open) [![Lint and Pytest](https://github.com/cirKITers/qml-essentials/actions/workflows/python-app.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/python-app.yml) [![Page Build](https://github.com/cirKITers/qml-essentials/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/pages/pages-build-deployment)
+[![version](https://img.shields.io/badge/version-0.1.12-green.svg)](https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/)  [![Quality](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml) [![Testing](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml) [![Documentation](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml)
+
 
 This repo contains some of the commonly used Ansaetze and coding stuff required for working with QML and Data-Reuploading models.
-There are also dedicated classes to calculate entanglement and expressiblity of a provided model as well as its Fourier coefficients.
+There are also dedicated classes to calculate entanglement and expressiblity of a provided model as well as its Fourier coefficients.
+
+Curious? :rocket: Get started by heading to the [setup page](setup.md).
+
+If you want to contribute, please refer to our [CONTRIBUTING guide](https://github.com/cirKITers/qml-essentials/blob/main/CONTRIBUTING.md) on Github.
+Oh and if you want to know what's being tested, checkout our [coverage report](coverage/index.html).
diff --git a/docs/setup.md b/docs/setup.md
@@ -1,14 +1,14 @@
 # Setup
 
-The package is available at [this index](https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum).
+This package is available via [PyPi](https://pypi.org/project/qml-essentials/).
+Installing this package is as simple as with any other package:
 
-There are two installation methods:
+`pip install qml-essentials`
 
-### [Poetry](https://python-poetry.org/)
+Or, if you prefer poetry:
 
-- `poetry source add --priority=supplemental quantum https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/+simple/`
-- `poetry add --source quantum qml-essentials`
+`poetry add qml-essentials`
 
-### pip
+Once you set things up, go ahead and checkout [how to use qml-essentials](usage.md).
 
-- `pip install --index-url https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/+simple/ qml-essentials`
+If you want to contribute to this project, a more detailled explaination is available in the [CONTRIBUTING guide](https://github.com/cirKITers/qml-essentials/blob/main/CONTRIBUTING.md). 
diff --git a/docs/usage.md b/docs/usage.md
@@ -22,7 +22,7 @@ print(model)
 Calling the model without any (`None`) values for the `params` and `inputs` argument, will implicitly call the model with the recently (or initial) parameters and `0`s as input.
 
 In the following we will describe some concepts of this class.
-For a more detailled reference on the methods and arguments that are available, please see the [references page](https://cirkiters.github.io/qml-essentials/references).
+For a more detailled reference on the methods and arguments that are available, please see the [references page](https://cirkiters.github.io/qml-essentials/references/#model).
 
 ## The essentials