Visualization module refactoring

.github/workflows/deploy-docs.yml

@@ -22,7 +22,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.11'
           cache: pip
@@ -36,7 +36,10 @@ jobs:
 
       - name: Build Sphinx docs
         working-directory: docs
-        run: make html
+        # ``-W`` promotes warnings to errors so doc regressions break CI
+        # rather than slipping through silently; ``--keep-going`` reports
+        # every offender in one run instead of stopping at the first.
+        run: python -m sphinx -W --keep-going -b html source build/html
 
       - name: Fix permissions
         run: |

.github/workflows/draft-pdf.yml

@@ -0,0 +1,34 @@
+name: Draft PDF
+on:
+  push:
+    paths:
+      - wetting_angle_kit_JOSS/**
+      - .github/workflows/draft-pdf.yml
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: wetting_angle_kit_JOSS/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: wetting_angle_kit_JOSS/paper.pdf
+      - name: Commit PDF to repository
+        uses: EndBug/add-and-commit@v9
+        with:
+          message: '(auto) Paper PDF Draft'
+          # This should be the path to the paper within your repo.
+          add: 'wetting_angle_kit_JOSS/paper.pdf' # 'paper/*.pdf' to commit all PDFs in the paper directory

.github/workflows/releases.yml

@@ -25,7 +25,7 @@ jobs:
         fetch-depth: 0
 
     - name: Set up Python 3.11
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.11'
 
@@ -47,6 +47,15 @@ jobs:
         release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
         exclude_labels: "duplicate,question,invalid,wontfix,dependency_updates,skip_changelog"
 
+    # CharMixer/auto-changelog-action above rewrites the changelog on the
+    # working tree; this step force-pushes the result back to the protected
+    # ``main`` branch. ``force: true`` is required because the changelog
+    # commit is fabricated by the action and would otherwise diverge from
+    # ``origin/main``; ``unprotect_reviews: true`` lifts branch-protection
+    # review requirements for the duration of the push so the workflow can
+    # publish the release autonomously. The push triggers
+    # ``deploy-docs.yml`` (push-to-main), which rebuilds and redeploys the
+    # documentation alongside this publish.
     - name: Update '${{ env.PUBLISH_UPDATE_BRANCH }}'
       uses: CasperWA/push-protected@v2
       with:
@@ -57,30 +66,6 @@ jobs:
         force: true
         tags: true
 
-    - name: Install docs dependencies
-      run: |
-        # Required to generate rst files from markdown
-        sudo apt install pandoc
-        pip install .[doc]
-
-    - name: Build Sphinx docs
-      working-directory: docs
-      run: |
-        # cannot use sphinx build directly as the makefile handles generation
-        # of some rst files
-        make html
-
-    - name: Fix permissions # following https://github.com/actions/upload-pages-artifact?tab=readme-ov-file#file-permissions
-      run: |
-        chmod -c -R +rX "./docs/build" | while read line; do
-          echo "::warning title=Invalid file permissions automatically fixed::$line"
-        done
-
-    - name: Upload docs artifact
-      uses: actions/upload-pages-artifact@v3
-      with:
-        path: ./docs/build/html
-
     - name: Get tagged versions
       run: echo "PREVIOUS_VERSION=$(git tag -l --sort -version:refname | sed -n 2p)" >> $GITHUB_ENV
 
@@ -117,17 +102,7 @@ jobs:
         user: __token__
         password: ${{ secrets.PYPI_PASSWORD }}
 
-  deploy_docs:
-    if: github.repository == 'Matgenix/wetting-angle-kit' && startsWith(github.ref, 'refs/tags/v')
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write      # to deploy to Pages
-      id-token: write   # to verify the deployment originates from an appropriate source
-    needs: publish
-    environment:
-      name: "Documentation"
-      url: https://Matgenix.github.io/wetting-angle-kit
-
-    steps:
-    - name: Deploy docs
-      uses: actions/deploy-pages@v4
+    # Documentation deployment is handled by ``deploy-docs.yml`` on push to
+    # ``main`` (which the ``Update main`` step above triggers). Keeping the
+    # build+deploy in a single workflow avoids the race that arises when
+    # both workflows publish to GitHub Pages simultaneously.

.github/workflows/testing.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v5
         with:
           python-version: '3.10'
           cache: pip
@@ -36,7 +36,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -50,7 +50,7 @@ jobs:
           pip install .[dev,all]
 
       - name: Test
-        run: pytest --cov=wetting_angle_kit --cov-report=xml --cov-fail-under=70
+        run: pytest --cov=wetting_angle_kit --cov-report=xml --cov-fail-under=80
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.11'
@@ -70,7 +70,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
           cache: pip
@@ -81,19 +81,19 @@ jobs:
           python -m pip install --upgrade pip
           pip install .[dev,ase]
 
-      - name: Test (skip OVITO-dependent tests)
-        run: |
-          pytest \
-            --ignore=tests/test_parser/test_parser_dump.py \
-            --ignore=tests/test_analysis
+      - name: Test
+        # OVITO-dependent test modules call ``pytest.importorskip("ovito")``
+        # at import time, so the full suite can run on macOS: those modules
+        # are skipped automatically and the ASE-backed tests still execute.
+        run: pytest
 
   docs:
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
           cache: pip
@@ -108,7 +108,7 @@ jobs:
 
       - name: Build Sphinx docs
         working-directory: docs
-        run: |
-          # cannot use sphinx build directly as the makefile handles generation
-          # of some rst files
-          make html
+        # ``-W`` promotes warnings to errors so doc regressions break CI
+        # rather than slipping through silently; ``--keep-going`` reports
+        # every offender in one run instead of stopping at the first.
+        run: python -m sphinx -W --keep-going -b html source build/html

.gitignore

@@ -77,6 +77,8 @@ docs/build/doctrees
 docs/build/generate-stamp
 
 docs/source/changelog.rst
+docs/build_log.txt
+docs/tutorials
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -30,7 +30,7 @@ repos:
   - id: rst-directive-colons
   - id: rst-inline-touching-normal
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.10.0
+  rev: v1.18.2
   hooks:
   - id: mypy
     files: ^src/wetting_angle_kit/

CITATION.cff

@@ -1,6 +1,8 @@
 cff-version: 1.2.0
 message: "If you use wetting-angle-kit in your research, please cite it using the metadata below."
 title: "wetting-angle-kit: a Python package to streamline the computation of wetting contact angles of nanodroplets on surfaces"
+version: 0.1.2
+date-released: "2026-06-01"
 type: software
 license: BSD-3-Clause
 repository-code: "https://github.com/Matgenix/wetting-angle-kit"

CONTRIBUTING.md

@@ -86,10 +86,9 @@ parsers' handling of orthogonal cells and periodic boundary conditions.
 
 ## Adding a new contact-angle method
 
-Subclass `BaseContactAngleAnalyzer`
+Subclass `BaseTrajectoryAnalyzer`
 ([src/wetting_angle_kit/analysis/analyzer.py](src/wetting_angle_kit/analysis/analyzer.py))
-and register it in the analyzer factory so it can be picked up by name.
-Add an integration test in `tests/test_analysis/` that
+and add an integration test in `tests/test_analysis/` that
 exercises the method on one of the fixture trajectories.
 
 ## Pull requests

README.md

@@ -1,6 +1,7 @@
 # wetting-angle-kit
 
 [![tests](https://img.shields.io/github/actions/workflow/status/Matgenix/wetting-angle-kit/testing.yml?branch=main&label=tests)](https://github.com/Matgenix/wetting-angle-kit/actions/workflows/testing.yml)
+[![docs](https://img.shields.io/github/actions/workflow/status/Matgenix/wetting-angle-kit/deploy-docs.yml?branch=main&label=docs)](https://github.com/Matgenix/wetting-angle-kit/actions/workflows/deploy-docs.yml)
 [![code coverage](https://codecov.io/gh/Matgenix/wetting-angle-kit/branch/main/graph/badge.svg)](https://codecov.io/gh/Matgenix/wetting-angle-kit)
 [![pypi version](https://img.shields.io/pypi/v/wetting-angle-kit?color=blue)](https://pypi.org/project/wetting-angle-kit/)
 [![Python versions](https://img.shields.io/pypi/pyversions/wetting-angle-kit)](https://pypi.org/project/wetting-angle-kit/)
@@ -55,8 +56,8 @@ conda install --strict-channel-priority -c https://conda.ovito.org -c conda-forg
 
 ```python
 from wetting_angle_kit.analysis import (
-    BinningContactAngleAnalyzer,
-    SlicingContactAngleAnalyzer,
+    BinningTrajectoryAnalyzer,
+    SlicingTrajectoryAnalyzer,
 )
 from wetting_angle_kit.parsers import XYZParser, XYZWaterFinder
 
@@ -69,22 +70,20 @@ oxygen_ids = finder.get_water_oxygen_indices(frame_index=0)
 
 parser = XYZParser(trajectory_file)
 
-slicing = SlicingContactAngleAnalyzer(
+slicing = SlicingTrajectoryAnalyzer(
     parser,
-    output_dir="out_slicing",
     atom_indices=oxygen_ids,
     droplet_geometry="spherical",
     delta_gamma=5,
 )
 results = slicing.analyze(frame_range=range(0, 50))
-print(results["mean_angle"], results["std_angle"])
+print(results.mean_angle, results.std_angle)
 
-binning = BinningContactAngleAnalyzer(
+binning = BinningTrajectoryAnalyzer(
     parser,
-    output_dir="out_binned",
     atom_indices=oxygen_ids,
     droplet_geometry="spherical",
 )
 results_binning = binning.analyze(frame_range=range(0, 200))
-print(results_binning["mean_angle"], results_binning["std_angle"])
+print(results_binning.mean_angle, results_binning.std_angle)
 ```

docs/Makefile

@@ -3,7 +3,11 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+# ``-W`` turns Sphinx warnings into errors; ``--keep-going`` finishes the
+# build so the user sees every offender rather than stopping at the first.
+# Override on the command line with ``SPHINXOPTS= make html`` for a lenient
+# local build.
+SPHINXOPTS    ?= -W --keep-going
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build