From 952f259b78fc2e48189be305b7cbd737423c69e6 Mon Sep 17 00:00:00 2001 From: John Pill Date: Wed, 2 Apr 2025 15:34:56 +0100 Subject: [PATCH 01/11] Added Interrogate git workflow --- .github/workflows/interrogate.yml | 34 +++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 .github/workflows/interrogate.yml diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml new file mode 100644 index 00000000..cc5d9875 --- /dev/null +++ b/.github/workflows/interrogate.yml @@ -0,0 +1,34 @@ +# This workflow will install and run the interrogate package to check for missing docstrings + + +name: Run interrogate + +on: push + +permissions: + contents: read + +jobs: + interrogate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Install dev dependencies + run: | + python -m pip install --upgrade pip + pip install .[dev] + - name: interrogate checks + run: | + python -m install interrogate + interrogate --fail-under 40 --ignore "*/__init__.py" --ignore "*/__main__.py" --output docstring-coverage.txt + ls -l + - name: Upload docstring-coverage + uses: actions/upload-artifact@v4 + with: + name: docstring-coverage + path: docstring-coverage.txt + if-no-files-found: warn From da93149e1c97057fa169184ab5b3189606b0a0c3 Mon Sep 17 00:00:00 2001 From: John Pill Date: Wed, 2 Apr 2025 15:37:43 +0100 Subject: [PATCH 02/11] Corrected Install --- .github/workflows/interrogate.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml index cc5d9875..129097e2 100644 --- a/.github/workflows/interrogate.yml +++ b/.github/workflows/interrogate.yml @@ -23,7 +23,7 @@ jobs: pip install .[dev] - name: interrogate checks run: | - python -m install interrogate + python -m pip install interrogate interrogate --fail-under 40 --ignore "*/__init__.py" --ignore "*/__main__.py" --output docstring-coverage.txt ls -l - name: Upload docstring-coverage From 144731bd6e5e66adb725769649c6a98324b7d8ba Mon Sep 17 00:00:00 2001 From: John Pill Date: Wed, 2 Apr 2025 15:39:47 +0100 Subject: [PATCH 03/11] Added exclusions --- .github/workflows/interrogate.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml index 129097e2..55d447a2 100644 --- a/.github/workflows/interrogate.yml +++ b/.github/workflows/interrogate.yml @@ -24,7 +24,7 @@ jobs: - name: interrogate checks run: | python -m pip install interrogate - interrogate --fail-under 40 --ignore "*/__init__.py" --ignore "*/__main__.py" --output docstring-coverage.txt + interrogate --fail-under 40 --exclude "*/__init__.py" --exclude "*/__main__.py" --output docstring-coverage.txt ls -l - name: Upload docstring-coverage uses: actions/upload-artifact@v4 From 3952a50570acf7da708c97dcf7dc719f6522632e Mon Sep 17 00:00:00 2001 From: John Pill Date: Wed, 2 Apr 2025 15:47:12 +0100 Subject: [PATCH 04/11] Added badge --- .github/workflows/interrogate.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml index 55d447a2..0863fd1e 100644 --- a/.github/workflows/interrogate.yml +++ b/.github/workflows/interrogate.yml @@ -24,7 +24,7 @@ jobs: - name: interrogate checks run: | python -m pip install interrogate - interrogate --fail-under 40 --exclude "*/__init__.py" --exclude "*/__main__.py" --output docstring-coverage.txt + interrogate -v --fail-under 40 --exclude "*/__init__.py" --exclude "*/__main__.py" --output docstring-coverage.txt --generate-badge badge.svg ls -l - name: Upload docstring-coverage uses: actions/upload-artifact@v4 @@ -32,3 +32,9 @@ jobs: name: docstring-coverage path: docstring-coverage.txt if-no-files-found: warn + - name: Upload interrogate badge + uses: actions/upload-artifact@v4 + with: + name: interrogate-badge + path: interrogate-badge.svg + if-no-files-found: warn From 89b0a72045956965c29a7333d53681c84876abcf Mon Sep 17 00:00:00 2001 From: John Pill Date: Wed, 2 Apr 2025 15:48:31 +0100 Subject: [PATCH 05/11] Added badge --- .github/workflows/interrogate.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml index 0863fd1e..3221beb3 100644 --- a/.github/workflows/interrogate.yml +++ b/.github/workflows/interrogate.yml @@ -24,7 +24,7 @@ jobs: - name: interrogate checks run: | python -m pip install interrogate - interrogate -v --fail-under 40 --exclude "*/__init__.py" --exclude "*/__main__.py" --output docstring-coverage.txt --generate-badge badge.svg + interrogate -v --fail-under 40 --exclude "*/__init__.py" --exclude "*/__main__.py" --output docstring-coverage.txt --generate-badge interrogate-badge.svg ls -l - name: Upload docstring-coverage uses: actions/upload-artifact@v4 From aeedccc8c31f73af9d72c0da225c22baa84f0157 Mon Sep 17 00:00:00 2001 From: John Pill Date: Wed, 2 Apr 2025 15:54:18 +0100 Subject: [PATCH 06/11] Added comments --- .github/workflows/interrogate.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml index 3221beb3..131b23e4 100644 --- a/.github/workflows/interrogate.yml +++ b/.github/workflows/interrogate.yml @@ -1,8 +1,9 @@ # This workflow will install and run the interrogate package to check for missing docstrings - name: Run interrogate +# Interrogate is currently triggered by pushes to the repository which is helpful for testing. +# Consider when we want to run interrogate, such as on pull-request. on: push permissions: From c67c386c0d3e5195839a6ac25941cfa841730f56 Mon Sep 17 00:00:00 2001 From: John Pill Date: Wed, 2 Apr 2025 15:57:44 +0100 Subject: [PATCH 07/11] Changed trigger to pull-request --- .github/workflows/interrogate.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml index 131b23e4..b872f414 100644 --- a/.github/workflows/interrogate.yml +++ b/.github/workflows/interrogate.yml @@ -2,9 +2,7 @@ name: Run interrogate -# Interrogate is currently triggered by pushes to the repository which is helpful for testing. -# Consider when we want to run interrogate, such as on pull-request. -on: push +on: pull_request permissions: contents: read From dcaa2eb9b23de120ae79330a96cf022d56696b46 Mon Sep 17 00:00:00 2001 From: John Pill Date: Fri, 4 Apr 2025 10:27:32 +0100 Subject: [PATCH 08/11] Added interrogate to dev packages and amended workflow --- .github/workflows/interrogate.yml | 3 +-- pyproject.toml | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml index b872f414..0e11e40c 100644 --- a/.github/workflows/interrogate.yml +++ b/.github/workflows/interrogate.yml @@ -2,7 +2,7 @@ name: Run interrogate -on: pull_request +on: push permissions: contents: read @@ -22,7 +22,6 @@ jobs: pip install .[dev] - name: interrogate checks run: | - python -m pip install interrogate interrogate -v --fail-under 40 --exclude "*/__init__.py" --exclude "*/__main__.py" --output docstring-coverage.txt --generate-badge interrogate-badge.svg ls -l - name: Upload docstring-coverage diff --git a/pyproject.toml b/pyproject.toml index 53ded445..a2be9e47 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,7 +44,7 @@ all = [ "pyearthtools-training[all] @ git+https://github.com/ACCESS-Community-Hub/PyEarthTools.git#subdirectory=packages/training" ] test = ["pytest", "pytest-cov", "pytest-xdist", "pudb"] -dev = ["pre-commit"] +dev = ["pre-commit", "interrogate"] docs = [ "sphinx", "myst-parser", From a4f854e391aa89036370d66c7f1f7001339a7adb Mon Sep 17 00:00:00 2001 From: John Pill Date: Fri, 4 Apr 2025 10:38:13 +0100 Subject: [PATCH 09/11] Update interrogate.yml --- .github/workflows/interrogate.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/interrogate.yml b/.github/workflows/interrogate.yml index 0e11e40c..0eb12d43 100644 --- a/.github/workflows/interrogate.yml +++ b/.github/workflows/interrogate.yml @@ -2,7 +2,7 @@ name: Run interrogate -on: push +on: pull_request permissions: contents: read From 93b4fb0fde012deeb19727fd7ecf9c56cb121fa0 Mon Sep 17 00:00:00 2001 From: John Pill Date: Fri, 4 Apr 2025 11:31:59 +0100 Subject: [PATCH 10/11] Update devguide.md Added Github Actions - Workflow section to add details about the automated actions being run and dev packages such as interrogate. --- docs/devguide.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/devguide.md b/docs/devguide.md index b8203c88..82ea3ceb 100644 --- a/docs/devguide.md +++ b/docs/devguide.md @@ -58,7 +58,17 @@ A code review is responsible for checking the following: 1. Unit test coverage is 100% and unit tests cover functionality and robustness (or improves the previous situation to these ends) 2. Any security issues are resolved and appropriately handled 3. Documentation and tutorials are written to cover any new functionality -4. Style guidelines are followed, static analysis and lint checking have been done -5. Code is readable and well-structured -6. Code does not do anything unexpected or beyond the scope of the function -7. Any additional dependencies are justified and do not result in bloat +5. Style guidelines are followed, static analysis and lint checking have been done +6. Code is readable and well-structured +7. Code does not do anything unexpected or beyond the scope of the function +8. Any additional dependencies are justified and do not result in bloat + + +## Github Actions - Workflows +We are using Github actions to automated testing and specific workflows. +1. **Black** - Python code formatting. https://pypi.org/project/black/ +2. **Interrogate** - will check the codebase docstring coverage and create a report. https://interrogate.readthedocs.io/en/latest/ + * To use manually run: `interrogate -v [PATH]` + * To run with a failing test float, exclusions, output file and badge run: `interrogate -v --fail-under 40 --exclude "*/__init__.py" --exclude "*/__main__.py" --output docstring-coverage.txt --generate-badge interrogate-badge.svg` + + From 2c855d7d2e4371e16be25e986b2b336e7f0f8f16 Mon Sep 17 00:00:00 2001 From: John Pill Date: Fri, 4 Apr 2025 11:42:34 +0100 Subject: [PATCH 11/11] Update devguide.md --- docs/devguide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/devguide.md b/docs/devguide.md index 82ea3ceb..4fe4df0b 100644 --- a/docs/devguide.md +++ b/docs/devguide.md @@ -58,10 +58,10 @@ A code review is responsible for checking the following: 1. Unit test coverage is 100% and unit tests cover functionality and robustness (or improves the previous situation to these ends) 2. Any security issues are resolved and appropriately handled 3. Documentation and tutorials are written to cover any new functionality -5. Style guidelines are followed, static analysis and lint checking have been done -6. Code is readable and well-structured -7. Code does not do anything unexpected or beyond the scope of the function -8. Any additional dependencies are justified and do not result in bloat +4. Style guidelines are followed, static analysis and lint checking have been done +5. Code is readable and well-structured +6. Code does not do anything unexpected or beyond the scope of the function +7. Any additional dependencies are justified and do not result in bloat ## Github Actions - Workflows