diff --git a/.github/workflows/publish_doc_pages.yml b/.github/workflows/publish_doc_pages.yml
index 4c43f87c..31de8314 100644
--- a/.github/workflows/publish_doc_pages.yml
+++ b/.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
diff --git a/.github/workflows/unit_test.yml b/.github/workflows/unit_test.yml
index 2466f447..161a3338 100644
--- a/.github/workflows/unit_test.yml
+++ b/.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 "alchem0x2a@gmail.com"
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 }}
diff --git a/README.md b/README.md
index 7afb46ac..93b35b45 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
[](https://anaconda.org/conda-forge/sparc-x-api)
[](https://pypi.org/project/sparc-x-api/)
-[](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)
[](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/unit_test.yml)
[](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/master/sparc/sparc_json_api/parameters.json)
[](https://sparc-x.github.io/SPARC-X-API/)
diff --git a/doc/Makefile b/doc/Makefile
index 02a1d6a3..3ea14457 100644
--- a/doc/Makefile
+++ b/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).
diff --git a/doc/contribute.md b/doc/contribute.md
index 5b7cd313..73e24f10 100644
--- a/doc/contribute.md
+++ b/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`.
+
## Notes for repo maintainers
diff --git a/doc/img/screenshots/coverage_example.png b/doc/img/screenshots/coverage_example.png
new file mode 100644
index 00000000..0c749eae
Binary files /dev/null and b/doc/img/screenshots/coverage_example.png differ
diff --git a/doc/index.md b/doc/index.md
index 4d45b50e..3ad3b8af 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -1,6 +1,5 @@
```{include} ../README.md
-:language: md
-:relative-docs: docs/
+:relative-docs: doc/
:relative-images:
```
diff --git a/doc/test_coverage.md b/doc/test_coverage.md
new file mode 100644
index 00000000..b2edc8cd
--- /dev/null
+++ b/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
+
+
+```