Merge pull request #283 from CCPBioSim/282-docs-regenerate-documentation

Regenerate API documentation and standardise Google-style docstrings

Author: harryswift01

.github/workflows/daily.yaml

@@ -1,4 +1,4 @@
-name: CodeEntropy Daily
+name: Daily Unit Tests
 
 on:
   schedule:

.github/workflows/pr.yaml

@@ -1,4 +1,4 @@
-name: CodeEntropy CI
+name: Pull Request CI
 
 on:
   pull_request:
@@ -79,27 +79,36 @@ jobs:
 
   docs:
     name: Docs
+    needs: unit
     runs-on: ubuntu-24.04
     timeout-minutes: 25
+
     steps:
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8
 
       - name: Set up Python 3.14
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: "3.14"
           cache: pip
 
-      - name: Install (docs)
+      - name: Install
         run: |
           python -m pip install --upgrade pip
           python -m pip install -e .[docs]
 
       - name: Build docs
         run: |
-          cd docs
-          make
+          make -C docs clean
+          make -C docs html SPHINXOPTS="-W --keep-going"
+
+      - name: Upload docs artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html
 
   pre-commit:
     name: Pre-commit

.github/workflows/release.yaml

@@ -1,4 +1,4 @@
-name: release
+name: Release CodeEntropy
 
 on:
   workflow_dispatch:

.github/workflows/weekly-docs.yaml

@@ -1,4 +1,4 @@
-name: CodeEntropy Weekly Docs
+name: Weekly Docs Build
 
 on:
   schedule:
@@ -19,6 +19,7 @@ jobs:
         os: [ubuntu-24.04, windows-2025, macos-15]
         python-version: ["3.12", "3.13", "3.14"]
     timeout-minutes: 30
+
     steps:
       - name: Checkout repo
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
@@ -31,11 +32,13 @@ jobs:
 
       - name: Install python dependencies
         run: |
-          pip install --upgrade pip
-          pip install -e .[docs]
+          python -m pip install --upgrade pip
+          python -m pip install -e .[docs]
 
-      - name: Build docs
-        run: cd docs && make
+      - name: Build docs (warnings as errors)
+        run: |
+          make -C docs clean
+          make -C docs html SPHINXOPTS="-W --keep-going"
 
       - name: Upload docs artifacts on failure
         if: failure()

.github/workflows/weekly-regression.yaml

@@ -1,4 +1,4 @@
-name: CodeEntropy Weekly Regression
+name: Weekly Regression Tests
 
 on:
   schedule:

.pre-commit-config.yaml

@@ -17,3 +17,20 @@ repos:
       - id: check-ast
       - id: end-of-file-fixer
       - id: trailing-whitespace
+
+  - repo: https://github.com/rstcheck/rstcheck
+    rev: v6.2.0
+    hooks:
+      - id: rstcheck
+        name: rstcheck (docstrings only)
+        files: \.py$
+        args: ["--report-level", "warning"]
+
+  - repo: local
+    hooks:
+      - id: sphinx-docs
+        name: sphinx-build (pre-push, warnings as errors)
+        entry: bash -lc 'make -C docs clean && make -C docs html SPHINXOPTS="-W --keep-going"'
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

CodeEntropy/config/argparse.py

@@ -4,13 +4,16 @@
 
 1) A declarative argument specification (`ARG_SPECS`) used to build an
    ``argparse.ArgumentParser``.
+
 2) A `ConfigResolver` that:
+
    - loads YAML configuration (if present),
    - merges YAML values with CLI values (CLI wins),
    - adjusts logging verbosity,
    - validates a subset of runtime inputs against the trajectory.
 
 Notes:
+
 - Boolean arguments are parsed via `str2bool` to support YAML/CLI interop and
   common string forms like "true"/"false".
 """

CodeEntropy/entropy/configurational.py

@@ -1,10 +1,10 @@
 """Conformational entropy utilities.
 
 This module provides:
-  * Assigning discrete conformational states for a single dihedral time series.
-  * Computing conformational entropy from a sequence of state labels.
 
-The public surface area is intentionally small to keep responsibilities clear.
+- Assignment of discrete conformational states for a single dihedral time series.
+- Computation of conformational entropy from a sequence of state labels.
+
 """
 
 from __future__ import annotations
@@ -127,15 +127,17 @@ def conformational_entropy_calculation(
         """Compute conformational entropy for a sequence of state labels.
 
         Entropy is computed as:
+
             S = -R * sum_i p_i * ln(p_i)
-        where p_i is the observed probability of state i in `states`.
+
+        where p_i is the observed probability of state i in ``states``.
 
         Args:
             states: Sequence/array of discrete state labels. Empty/None yields 0.0.
             number_frames: Frame count metadata.
 
         Returns:
-            Conformational entropy in J/mol/K.
+            float: Conformational entropy in J/mol/K.
         """
         _ = number_frames
 

CodeEntropy/entropy/workflow.py

@@ -2,13 +2,13 @@
 
 This module defines `EntropyWorkflow`, which coordinates the end-to-end entropy
 workflow:
-  * Determine trajectory bounds and frame count.
-  * Build a reduced universe based on atom selection.
-  * Identify molecule groups and hierarchy levels.
-  * Optionally compute water entropy and adjust selection.
-  * Execute the level DAG (matrix/state preparation).
-  * Execute the entropy graph (entropy calculations and aggregation).
-  * Finalize and persist results.
+- Determine trajectory bounds and frame count.
+- Build a reduced universe based on atom selection.
+- Identify molecule groups and hierarchy levels.
+- Optionally compute water entropy and adjust selection.
+- Execute the level DAG (matrix/state preparation).
+- Execute the entropy graph (entropy calculations and aggregation).
+- Finalize and persist results.
 
 The manager intentionally delegates calculations to dedicated components.
 """

CodeEntropy/levels/axes.py

@@ -24,18 +24,20 @@ class AxesCalculator:
     rotation, and handling bead-based representations of molecular systems.
 
     Provides utility methods to:
-      - extract averaged positions,
-      - convert coordinates to spherical systems (future/legacy scope),
-      - compute axes used to rotate forces around,
-      - compute custom moments of inertia,
-      - manipulate vectors under periodic boundary conditions (PBC),
-      - construct custom moment-of-inertia tensors and principal axes.
+
+    - Extract averaged positions.
+    - Convert coordinates to spherical systems (future/legacy scope).
+    - Compute axes used to rotate forces around.
+    - Compute custom moments of inertia.
+    - Manipulate vectors under periodic boundary conditions (PBC).
+    - Construct custom moment-of-inertia tensors and principal axes.
 
     Notes:
-        This class deliberately does **not**:
-          - compute weighted forces/torques (that belongs in ForceTorqueCalculator),
-          - build covariances,
-          - compute entropies.
+        This class deliberately does not:
+
+        - Compute weighted forces/torques (that belongs in ForceTorqueCalculator).
+        - Build covariances.
+        - Compute entropies.
     """
 
     def __init__(self) -> None:
@@ -363,7 +365,7 @@ def get_vanilla_axes(self, molecule):
         Returns:
             Tuple[np.ndarray, np.ndarray]:
                 - principal_axes: (3, 3) axes.
-                - moment_of_inertia: (3,) moments sorted descending by |value|.
+                - moment_of_inertia: (3,) moments sorted descending by absolute value.
         """
         moment_of_inertia_tensor = molecule.moment_of_inertia(unwrap=True)
         make_whole(molecule.atoms)
@@ -388,13 +390,13 @@ def get_custom_axes(
 
         - axis1: use the normalised vector ab as axis1. If there is more than one
           bonded heavy atom (HA), average over all the normalised vectors
-          calculated from b_list and use this as axis1). b_list contains all the
+          calculated from b_list and use this as axis1. b_list contains all the
           bonded heavy atom coordinates.
 
         - axis2: use the cross product of normalised vector ac and axis1 as axis2.
           If there are more than two bonded heavy atoms, then use normalised vector
-          b[0]c to cross product with axis1, this gives the axis perpendicular
-          (represented by |_ symbol below) to axis1.
+          b[0]c to cross product with axis1. This gives the axis perpendicular
+          to axis1.
 
         - axis3: the cross product of axis1 and axis2, which is perpendicular to
           axis1 and axis2.
@@ -405,12 +407,12 @@ def get_custom_axes(
             c: Coordinates of a second heavy atom or a hydrogen atom.
             dimensions: Simulation box dimensions (3,).
 
-        ::
+        .. code-block:: text
 
             a          1 = norm_ab
-           / \         2 = |_ norm_ab and norm_ac (use bc if more than 2 HAs)
-          /   \        3 = |_ 1 and 2
-        b       c
+           / \         2 = perpendicular to norm_ab and norm_ac (or bc if >2 HAs)
+          /   \        3 = perpendicular to 1 and 2
+         b     c
 
         Returns:
             np.ndarray: (3, 3) array of the axes used to rotate forces.
@@ -458,8 +460,10 @@ def get_custom_moment_of_inertia(
         heavy atom position in a UA).
 
         Original behaviour preserved:
+
         - Uses PBC-aware translated coordinates.
-        - Sums contributions from each atom: |axis x r|^2 * mass.
+        - Sums contributions from each atom using the squared norm of (axis × r)
+          multiplied by mass.
         - Removes the lowest MOI degree of freedom if the UA only has a single
           bonded H (i.e. UA has 2 atoms total).
 
@@ -581,6 +585,7 @@ def get_custom_principal_axes(
         built-in MDAnalysis principal_axes() function.
 
         Original behaviour preserved:
+
         - Eigenvalues are sorted by descending absolute magnitude.
         - Eigenvectors are transposed so axes are returned as rows.
         - Z axis is flipped to enforce the same handedness convention as the