Merge pull request #76 from alchem0x2A/master

Add coverage report / workflow to documentation

.github/workflows/publish_doc_pages.yml

@@ -5,14 +5,21 @@ on:
   push:
     branches:
       - master
+      - badges
+    paths:
       - 'doc/**'
       - 'sparc/**'
+      - '.coverage'
+      - '.github/workflows/publish_doc_pages.yml'
   pull_request:
     branches:
       - master
+      - badges
     paths:
       - 'doc/**'
       - 'sparc/**'
+      - '.coverage'
+      - '.github/workflows/publish_doc_pages.yml'
 
   workflow_dispatch:
 
@@ -24,7 +31,19 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
+    - name: Checkout the latest .coverage file from badges branch
+      uses: actions/checkout@v4
+      with:
+        ref: badges
+        path: coverage
+    - name: List current files
+      run: |
+        if [ -f coverage/.coverage ]; then
+            cp coverage/.coverage .
+        fi
+        ls -al coverage/
+        ls -al .
     - uses: conda-incubator/setup-miniconda@v3
       with:
         python-version: "3.11"
@@ -35,9 +54,16 @@ jobs:
     - name: Install doc-build dependencies
       run: |
         pip install -e ".[doc]"
+    - name: Generate coverage files
+      run: |
+        mkdir -p doc/_static
+        if [ -f .coverage ]; then
+            coverage html --omit="tests/*.py" -d doc/_static/htmlcov
+        fi
+        ls -al .
+        ls -al doc/_static
     - name: Build sphix doc
       run: |
-        # sphinx-build doc doc/_build
         cd doc
         make clean && make html
     - name: Deploy to github pages

.github/workflows/unit_test.yml

@@ -55,23 +55,25 @@ jobs:
       run: |
         mkdir -p badges/
         # A coverage test badge
-        anybadge --value=$COVPERCENT --file=badges/coverage.svg coverage
+        anybadge --value=$COVPERCENT --file=badges/coverage.svg -l "Test Coverage"
         # A version badge
         PIPVER=`pip show sparc-x-api | grep Version | cut -d ' ' -f2`
         anybadge --value=$PIPVER --file=badges/package.svg -l sparc-x-api
         # api version badge
         anybadge --value=${API_VERSION} --file=badges/api_version.svg -l "JSON schema version"
-    - name: Manually add git badges
+    - name: Manually add git badges and .coverage file
       run: |
         # Assuming a badges branch already exists!
         rm -rf /tmp/*.svg && cp badges/*.svg /tmp/
+        rm -rf /tmp/.coverage && mv .coverage /tmp/
         git fetch
         git switch badges || { echo "Could not check out badges branch. Have you created it on remote?"; exit 1; }
         git pull
         cp /tmp/*.svg badges/ && git add -f badges/*.svg && rm -rf /tmp/*.svg
+        cp /tmp/.coverage ./ && git add -f .coverage && rm -rf /tmp/.coverage
         git config --global user.email "[email protected]"
         git config --global user.name "Github Action Bot (badges only)"
-        git commit -m "Update badges from run ${RID}" || true
+        git commit -m "Update badges and coverge file from run ${RID}" || true
         git push -u origin badges || true
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -2,7 +2,7 @@
 <!-- [![Package](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/package.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/package.svg) -->
 [![Conda Version](https://img.shields.io/conda/v/conda-forge/sparc-x-api)](https://anaconda.org/conda-forge/sparc-x-api)
 [![PyPI - Version](https://img.shields.io/pypi/v/sparc-x-api)](https://pypi.org/project/sparc-x-api/)
-[![Coverage](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/coverage.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/coverage.svg)
+[![Coverage](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/coverage.svg)](https://sparc-x-api.github.io/SPARC-X-API/test_coverage.html)
 [![Unit tests for SPARC-X-API](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/unit_test.yml/badge.svg)](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/unit_test.yml)
 [![JSON-API](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/api_version.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/master/sparc/sparc_json_api/parameters.json)
 [![Doc](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/doc.svg)](https://sparc-x.github.io/SPARC-X-API/)

doc/Makefile

@@ -18,7 +18,7 @@ apidoc:
 	@$(SPHINXDOC) -f -e -M -o "$(SOURCEDIR)"/api "$(SOURCEDIR)"/../sparc
 
 
-.PHONY: help Makefile apidoc
+.PHONY: help Makefile apidoc coverage
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

doc/contribute.md

@@ -78,6 +78,28 @@ environment variables are set (may subject to changes):
   - Setting up correct SPARC command (e.g. via `ASE_SPARC_COMMAND`)
   - Having socket-compatible SPARC binary
 
+### Checking test coverage
+
+You could use the `coverage` package to generate a coverage report for
+the test codes. The current coverage report for the master branch of
+SPARC-X-API can be accessed [here](test_coverage.md).
+
+If running locally, please use the following commands:
+```bash
+# Set up proper environment variables first
+# Run the code at the repo root
+coverage run -a -m pytest -svv tests/
+coverage html --omit="tests/*.py"
+```
+
+which will generate a folder `htmlcov` under the repo root. Open
+`htmlcov/index.html` in a browser to see the coverage broken down to
+files and lines, as shown in the following screenshot:
+```{figure} img/screenshots/coverage_example.png
+:figwidth: 80 %
+:align: center
+```
+
 ### Editing documentation
 
 Source files for documentation are placed under `doc/` directory,
@@ -115,7 +137,7 @@ that are important for demonstrating the functionalities of
 `SPARC-X-API` while the calculations can be finished using moderate
 computating power (e.g. a few minutes with 4 CPU cores).
 
-The examples can have the name in the format `ex[Number]-[purpose].py`.
+<!-- The examples can have the name in the format `ex[Number]-[purpose].py`. -->
 
 ## Notes for repo maintainers
 

doc/index.md

@@ -1,6 +1,5 @@
 ```{include} ../README.md
-:language: md
-:relative-docs: docs/
+:relative-docs: doc/
 :relative-images:
 ```
 

doc/test_coverage.md

@@ -0,0 +1,23 @@
+# Test Coverage Report
+
+The following coverage test was generated by the [`coverage` package](https://coverage.readthedocs.io/en/7.6.7/other.html):
+
+```{raw} html
+<iframe id="coverage-iframe"
+        src="_static/htmlcov/index.html"
+		width="100%"
+		style="border:none;"></iframe>
+<script>
+    function adjustIframeHeight() {
+        var iframe = document.getElementById('coverage-iframe');
+        if (iframe && iframe.contentWindow && iframe.contentWindow.document.body) {
+            iframe.style.height = (iframe.contentWindow.document.body.scrollHeight + 50) + 'px';
+        }
+    }
+
+    document.addEventListener("DOMContentLoaded", function() {
+        const iframe = document.getElementById('coverage-iframe');
+        iframe.onload = adjustIframeHeight;  // Adjust height when iframe content loads
+    });
+</script>
+```