diff --git a/.github/workflows/daily.yaml b/.github/workflows/daily.yaml index 218e8345..74d1ec7c 100644 --- a/.github/workflows/daily.yaml +++ b/.github/workflows/daily.yaml @@ -1,4 +1,4 @@ -name: CodeEntropy Daily +name: Daily Unit Tests on: schedule: diff --git a/.github/workflows/pr.yaml b/.github/workflows/pr.yaml index a53493f4..b9d2b892 100644 --- a/.github/workflows/pr.yaml +++ b/.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 diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 05102594..892367cf 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -1,4 +1,4 @@ -name: release +name: Release CodeEntropy on: workflow_dispatch: diff --git a/.github/workflows/weekly-docs.yaml b/.github/workflows/weekly-docs.yaml index 6c38e5b3..5f56a0d7 100644 --- a/.github/workflows/weekly-docs.yaml +++ b/.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() diff --git a/.github/workflows/weekly-regression.yaml b/.github/workflows/weekly-regression.yaml index 7c8fa5a3..ad17ae88 100644 --- a/.github/workflows/weekly-regression.yaml +++ b/.github/workflows/weekly-regression.yaml @@ -1,4 +1,4 @@ -name: CodeEntropy Weekly Regression +name: Weekly Regression Tests on: schedule: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ca087bfa..eb249f5f 100644 --- a/.pre-commit-config.yaml +++ b/.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] diff --git a/CodeEntropy/config/argparse.py b/CodeEntropy/config/argparse.py index ec737301..98ff4432 100644 --- a/CodeEntropy/config/argparse.py +++ b/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". """ diff --git a/CodeEntropy/entropy/configurational.py b/CodeEntropy/entropy/configurational.py index be6c31cd..c3b908c8 100644 --- a/CodeEntropy/entropy/configurational.py +++ b/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 diff --git a/CodeEntropy/entropy/workflow.py b/CodeEntropy/entropy/workflow.py index c5a76652..d79b46e3 100644 --- a/CodeEntropy/entropy/workflow.py +++ b/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. """ diff --git a/CodeEntropy/levels/axes.py b/CodeEntropy/levels/axes.py index 07f1918f..2d05fcb3 100644 --- a/CodeEntropy/levels/axes.py +++ b/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 diff --git a/CodeEntropy/levels/dihedrals.py b/CodeEntropy/levels/dihedrals.py index ff5bf853..ccdad688 100644 --- a/CodeEntropy/levels/dihedrals.py +++ b/CodeEntropy/levels/dihedrals.py @@ -47,7 +47,7 @@ def build_conformational_states( residue-level state generation depending on which hierarchy levels are enabled per molecule. - Progress reporting is optional and UI-agnostic: if a progress sink is + Progress reporting is optional and UI-agnostic. If a progress sink is provided, the method will create a single task and advance it once per molecule group. @@ -66,17 +66,17 @@ def build_conformational_states( Must expose add_task(), update(), and advance(). Returns: - Tuple of: - states_ua: Dict mapping (group_id, local_residue_id) -> list of state - labels (strings) across the analyzed trajectory. - states_res: List-like structure indexed by group_id (or equivalent) - containing residue-level state labels (strings) across the - analyzed trajectory. + tuple: (states_ua, states_res) + + - states_ua: Dict mapping (group_id, local_residue_id) -> list of state + labels (strings) across the analyzed trajectory. + - states_res: Structure indexed by group_id (or equivalent) containing + residue-level state labels (strings) across the analyzed trajectory. Notes: - This function advances progress once per group_id. - Frame slicing arguments (start/end/step) are forwarded to downstream - helpers as implemented in this module. + helpers as implemented in this module. """ number_groups = len(groups) states_ua: Dict[UAKey, List[str]] = {} diff --git a/CodeEntropy/levels/hierarchy.py b/CodeEntropy/levels/hierarchy.py index 76c23311..863443fd 100644 --- a/CodeEntropy/levels/hierarchy.py +++ b/CodeEntropy/levels/hierarchy.py @@ -1,14 +1,16 @@ """Hierarchy level selection and bead construction. -This module defines `HierarchyBuilder`, which is responsible for: - 1) Determining which hierarchy levels apply to each molecule. - 2) Constructing "beads" (AtomGroups) for a given molecule at a given level. +This module defines ``HierarchyBuilder``, which is responsible for: + +- Determining which hierarchy levels apply to each molecule. +- Constructing "beads" (AtomGroups) for a given molecule at a given level. Notes: -- The "residue" bead construction must use residues attached to the provided - AtomGroup/container. Using `resindex` selection strings is unsafe because - `resindex` is global to the Universe and can produce empty/incorrect beads - when operating on per-molecule containers beyond the first molecule. + The "residue" bead construction must use residues attached to the provided + AtomGroup/container. Using ``resindex`` selection strings is unsafe because + ``resindex`` is global to the Universe and can produce empty or incorrect + beads when operating on per-molecule containers beyond the first molecule. + """ from __future__ import annotations diff --git a/CodeEntropy/levels/mda.py b/CodeEntropy/levels/mda.py index c76b6f50..308157bd 100644 --- a/CodeEntropy/levels/mda.py +++ b/CodeEntropy/levels/mda.py @@ -136,15 +136,18 @@ def merge_forces( """Create a universe by merging coordinates and forces from different files. This method loads: - - coordinates + dimensions from the coordinate trajectory (tprfile + trrfile) - - forces from the force trajectory (tprfile + forcefile) - If the force trajectory does not expose forces in MDAnalysis (e.g. the file + - Coordinates and dimensions from the coordinate trajectory + (``tprfile`` + ``trrfile``). + - Forces from the force trajectory (``tprfile`` + ``forcefile``). + + If the force trajectory does not expose forces in MDAnalysis (e.g., the file does not contain forces, or the reader does not provide them), then: - - if `fallback_to_positions_if_no_forces` is True, positions from the force - trajectory are used as the "forces" array (backwards-compatible behaviour - with earlier implementations). - - otherwise, the underlying `NoDataError` is raised. + + - If ``fallback_to_positions_if_no_forces`` is True, positions from the + force trajectory are used as the "forces" array (backwards-compatible + behaviour with earlier implementations). + - Otherwise, the underlying ``NoDataError`` is raised. Args: tprfile: Topology input file. @@ -155,14 +158,15 @@ def merge_forces( recognised by MDAnalysis. kcal: If True, scale the force array by 4.184 to convert from kcal to kJ. force_format: Optional file format for the force trajectory. If not - provided, uses `fileformat`. + provided, uses ``fileformat``. fallback_to_positions_if_no_forces: If True, and the force trajectory has no accessible forces, use positions from the force trajectory as a fallback (legacy behaviour). Returns: - A new Universe containing coordinates, forces and dimensions loaded into - memory. + MDAnalysis.Universe: A new Universe containing coordinates, forces and + dimensions loaded into memory. + """ logger.debug("Loading coordinate Universe with %s", trrfile) u = mda.Universe(tprfile, trrfile, format=fileformat) diff --git a/CodeEntropy/levels/nodes/covariance.py b/CodeEntropy/levels/nodes/covariance.py index 1085aad4..dd56d180 100644 --- a/CodeEntropy/levels/nodes/covariance.py +++ b/CodeEntropy/levels/nodes/covariance.py @@ -37,13 +37,15 @@ class FrameCovarianceNode: This node computes per-frame second-moment matrices (outer products) for force and torque generalized vectors at hierarchy levels: - - united_atom - - residue - - polymer + + - united_atom + - residue + - polymer Within a single frame, outputs are incrementally averaged across molecules that belong to the same group. Frame-to-frame accumulation is handled elsewhere (by a higher-level reducer). + """ def __init__(self) -> None: diff --git a/CodeEntropy/molecules/grouping.py b/CodeEntropy/molecules/grouping.py index 79f0b145..3d3a5f29 100644 --- a/CodeEntropy/molecules/grouping.py +++ b/CodeEntropy/molecules/grouping.py @@ -31,9 +31,9 @@ class GroupingConfig: Attributes: strategy: Grouping strategy name. Supported values are: - - "each": each molecule gets its own group. - - "molecules": group molecules by chemical signature - (atom count + atom names in order). + - "each": each molecule gets its own group. + - "molecules": group molecules by chemical signature + (atom count + atom names in order). """ strategy: str diff --git a/CodeEntropy/results/reporter.py b/CodeEntropy/results/reporter.py index f9579f38..c411139e 100644 --- a/CodeEntropy/results/reporter.py +++ b/CodeEntropy/results/reporter.py @@ -95,13 +95,15 @@ class ResultsReporter: """Collect, format, and output entropy calculation results. This reporter accumulates: - - Molecule-level results (group_id, level, entropy_type, value) - - Residue-level results (group_id, resname, level, entropy_type, frame_count, + + - Molecule-level results (group_id, level, entropy_type, value) + - Residue-level results (group_id, resname, level, entropy_type, frame_count, value) - - Group metadata labels (label, residue_count, atom_count) + - Group metadata labels (label, residue_count, atom_count) It can render tables using Rich and export grouped results to JSON with basic provenance metadata. + """ def __init__(self, console: Optional[Console] = None) -> None: diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index cc91d767..00000000 --- a/docs/api.rst +++ /dev/null @@ -1,69 +0,0 @@ -API Documentation -================= - -Main ----- -.. autosummary:: - :toctree: autosummary - - CodeEntropy.main.main - -Run Manager ------------- -.. autosummary:: - :toctree: autosummary - - CodeEntropy.run.RunManager - CodeEntropy.run.RunManager.create_job_folder - CodeEntropy.run.RunManager.run_entropy_workflow - CodeEntropy.run.RunManager.new_U_select_frame - CodeEntropy.run.RunManager.new_U_select_atom - -Level Manager -------------- -.. autosummary:: - :toctree: autosummary - - CodeEntropy.levels.LevelManager - CodeEntropy.levels.LevelManager.select_levels - CodeEntropy.levels.LevelManager.get_matrices - CodeEntropy.levels.LevelManager.get_dihedrals - CodeEntropy.levels.LevelManager.compute_dihedral_conformations - CodeEntropy.levels.LevelManager.get_beads - CodeEntropy.levels.LevelManager.get_axes - CodeEntropy.levels.LevelManager.get_avg_pos - CodeEntropy.levels.LevelManager.get_sphCoord_axes - CodeEntropy.levels.LevelManager.get_weighted_forces - CodeEntropy.levels.LevelManager.get_weighted_torques - CodeEntropy.levels.LevelManager.create_submatrix - CodeEntropy.levels.LevelManager.build_covariance_matrices - CodeEntropy.levels.LevelManager.update_force_torque_matrices - CodeEntropy.levels.LevelManager.filter_zero_rows_columns - CodeEntropy.levels.LevelManager.build_conformational_states - -Entropy Manager ---------------- -.. autosummary:: - :toctree: autosummary - - CodeEntropy.entropy.EntropyManager - CodeEntropy.entropy.EntropyManager.execute - -Vibrational Entropy -^^^^^^^^^^^^^^^^^^^ -.. autosummary:: - :toctree: autosummary - - CodeEntropy.entropy.VibrationalEntropy - CodeEntropy.entropy.VibrationalEntropy.frequency_calculation - CodeEntropy.entropy.VibrationalEntropy.vibrational_entropy_calculation - - -Conformational Entropy -^^^^^^^^^^^^^^^^^^^^^^ -.. autosummary:: - :toctree: autosummary - - CodeEntropy.entropy.ConformationalEntropy - CodeEntropy.entropy.ConformationalEntropy.assign_conformation - CodeEntropy.entropy.ConformationalEntropy.conformational_entropy_calculation diff --git a/docs/api/CodeEntropy.cli.rst b/docs/api/CodeEntropy.cli.rst new file mode 100644 index 00000000..8166c64f --- /dev/null +++ b/docs/api/CodeEntropy.cli.rst @@ -0,0 +1,7 @@ +CodeEntropy.cli module +====================== + +.. automodule:: CodeEntropy.cli + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.config.argparse.rst b/docs/api/CodeEntropy.config.argparse.rst new file mode 100644 index 00000000..5531f0f4 --- /dev/null +++ b/docs/api/CodeEntropy.config.argparse.rst @@ -0,0 +1,7 @@ +CodeEntropy.config.argparse module +================================== + +.. automodule:: CodeEntropy.config.argparse + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.config.rst b/docs/api/CodeEntropy.config.rst new file mode 100644 index 00000000..c85bcb89 --- /dev/null +++ b/docs/api/CodeEntropy.config.rst @@ -0,0 +1,16 @@ +CodeEntropy.config package +========================== + +.. automodule:: CodeEntropy.config + :members: + :show-inheritance: + :undoc-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.config.argparse + CodeEntropy.config.runtime diff --git a/docs/api/CodeEntropy.config.runtime.rst b/docs/api/CodeEntropy.config.runtime.rst new file mode 100644 index 00000000..c942c9a0 --- /dev/null +++ b/docs/api/CodeEntropy.config.runtime.rst @@ -0,0 +1,7 @@ +CodeEntropy.config.runtime module +================================= + +.. automodule:: CodeEntropy.config.runtime + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.core.logging.rst b/docs/api/CodeEntropy.core.logging.rst new file mode 100644 index 00000000..2b61ad34 --- /dev/null +++ b/docs/api/CodeEntropy.core.logging.rst @@ -0,0 +1,7 @@ +CodeEntropy.core.logging module +=============================== + +.. automodule:: CodeEntropy.core.logging + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.core.rst b/docs/api/CodeEntropy.core.rst new file mode 100644 index 00000000..9457905b --- /dev/null +++ b/docs/api/CodeEntropy.core.rst @@ -0,0 +1,15 @@ +CodeEntropy.core package +======================== + +.. automodule:: CodeEntropy.core + :members: + :show-inheritance: + :undoc-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.core.logging diff --git a/docs/api/CodeEntropy.entropy.configurational.rst b/docs/api/CodeEntropy.entropy.configurational.rst new file mode 100644 index 00000000..3ab77362 --- /dev/null +++ b/docs/api/CodeEntropy.entropy.configurational.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.configurational module +========================================== + +.. automodule:: CodeEntropy.entropy.configurational + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.entropy.graph.rst b/docs/api/CodeEntropy.entropy.graph.rst new file mode 100644 index 00000000..d6b23043 --- /dev/null +++ b/docs/api/CodeEntropy.entropy.graph.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.graph module +================================ + +.. automodule:: CodeEntropy.entropy.graph + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.entropy.nodes.aggregate.rst b/docs/api/CodeEntropy.entropy.nodes.aggregate.rst new file mode 100644 index 00000000..b0bfe716 --- /dev/null +++ b/docs/api/CodeEntropy.entropy.nodes.aggregate.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.nodes.aggregate module +========================================== + +.. automodule:: CodeEntropy.entropy.nodes.aggregate + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.entropy.nodes.configurational.rst b/docs/api/CodeEntropy.entropy.nodes.configurational.rst new file mode 100644 index 00000000..93f66f70 --- /dev/null +++ b/docs/api/CodeEntropy.entropy.nodes.configurational.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.nodes.configurational module +================================================ + +.. automodule:: CodeEntropy.entropy.nodes.configurational + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.entropy.nodes.rst b/docs/api/CodeEntropy.entropy.nodes.rst new file mode 100644 index 00000000..02c19511 --- /dev/null +++ b/docs/api/CodeEntropy.entropy.nodes.rst @@ -0,0 +1,17 @@ +CodeEntropy.entropy.nodes package +================================= + +.. automodule:: CodeEntropy.entropy.nodes + :members: + :show-inheritance: + :undoc-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.entropy.nodes.aggregate + CodeEntropy.entropy.nodes.configurational + CodeEntropy.entropy.nodes.vibrational diff --git a/docs/api/CodeEntropy.entropy.nodes.vibrational.rst b/docs/api/CodeEntropy.entropy.nodes.vibrational.rst new file mode 100644 index 00000000..bf2183c4 --- /dev/null +++ b/docs/api/CodeEntropy.entropy.nodes.vibrational.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.nodes.vibrational module +============================================ + +.. automodule:: CodeEntropy.entropy.nodes.vibrational + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.entropy.orientational.rst b/docs/api/CodeEntropy.entropy.orientational.rst new file mode 100644 index 00000000..82214e8b --- /dev/null +++ b/docs/api/CodeEntropy.entropy.orientational.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.orientational module +======================================== + +.. automodule:: CodeEntropy.entropy.orientational + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.entropy.rst b/docs/api/CodeEntropy.entropy.rst new file mode 100644 index 00000000..99ed6b3f --- /dev/null +++ b/docs/api/CodeEntropy.entropy.rst @@ -0,0 +1,28 @@ +CodeEntropy.entropy package +=========================== + +.. automodule:: CodeEntropy.entropy + :members: + :show-inheritance: + :undoc-members: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.entropy.nodes + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.entropy.configurational + CodeEntropy.entropy.graph + CodeEntropy.entropy.orientational + CodeEntropy.entropy.vibrational + CodeEntropy.entropy.water + CodeEntropy.entropy.workflow diff --git a/docs/api/CodeEntropy.entropy.vibrational.rst b/docs/api/CodeEntropy.entropy.vibrational.rst new file mode 100644 index 00000000..cd7dc90e --- /dev/null +++ b/docs/api/CodeEntropy.entropy.vibrational.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.vibrational module +====================================== + +.. automodule:: CodeEntropy.entropy.vibrational + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.entropy.water.rst b/docs/api/CodeEntropy.entropy.water.rst new file mode 100644 index 00000000..7e4e807b --- /dev/null +++ b/docs/api/CodeEntropy.entropy.water.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.water module +================================ + +.. automodule:: CodeEntropy.entropy.water + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.entropy.workflow.rst b/docs/api/CodeEntropy.entropy.workflow.rst new file mode 100644 index 00000000..0913a3e8 --- /dev/null +++ b/docs/api/CodeEntropy.entropy.workflow.rst @@ -0,0 +1,7 @@ +CodeEntropy.entropy.workflow module +=================================== + +.. automodule:: CodeEntropy.entropy.workflow + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.axes.rst b/docs/api/CodeEntropy.levels.axes.rst new file mode 100644 index 00000000..82d2146e --- /dev/null +++ b/docs/api/CodeEntropy.levels.axes.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.axes module +============================== + +.. automodule:: CodeEntropy.levels.axes + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.dihedrals.rst b/docs/api/CodeEntropy.levels.dihedrals.rst new file mode 100644 index 00000000..a69952a9 --- /dev/null +++ b/docs/api/CodeEntropy.levels.dihedrals.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.dihedrals module +=================================== + +.. automodule:: CodeEntropy.levels.dihedrals + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.forces.rst b/docs/api/CodeEntropy.levels.forces.rst new file mode 100644 index 00000000..a9297ffc --- /dev/null +++ b/docs/api/CodeEntropy.levels.forces.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.forces module +================================ + +.. automodule:: CodeEntropy.levels.forces + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.frame_dag.rst b/docs/api/CodeEntropy.levels.frame_dag.rst new file mode 100644 index 00000000..9a747a87 --- /dev/null +++ b/docs/api/CodeEntropy.levels.frame_dag.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.frame\_dag module +==================================== + +.. automodule:: CodeEntropy.levels.frame_dag + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.hierarchy.rst b/docs/api/CodeEntropy.levels.hierarchy.rst new file mode 100644 index 00000000..c09c435e --- /dev/null +++ b/docs/api/CodeEntropy.levels.hierarchy.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.hierarchy module +=================================== + +.. automodule:: CodeEntropy.levels.hierarchy + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.level_dag.rst b/docs/api/CodeEntropy.levels.level_dag.rst new file mode 100644 index 00000000..78c08786 --- /dev/null +++ b/docs/api/CodeEntropy.levels.level_dag.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.level\_dag module +==================================== + +.. automodule:: CodeEntropy.levels.level_dag + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.linalg.rst b/docs/api/CodeEntropy.levels.linalg.rst new file mode 100644 index 00000000..b0adad18 --- /dev/null +++ b/docs/api/CodeEntropy.levels.linalg.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.linalg module +================================ + +.. automodule:: CodeEntropy.levels.linalg + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.mda.rst b/docs/api/CodeEntropy.levels.mda.rst new file mode 100644 index 00000000..cda20a25 --- /dev/null +++ b/docs/api/CodeEntropy.levels.mda.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.mda module +============================= + +.. automodule:: CodeEntropy.levels.mda + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.nodes.accumulators.rst b/docs/api/CodeEntropy.levels.nodes.accumulators.rst new file mode 100644 index 00000000..dbe0ef2a --- /dev/null +++ b/docs/api/CodeEntropy.levels.nodes.accumulators.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.nodes.accumulators module +============================================ + +.. automodule:: CodeEntropy.levels.nodes.accumulators + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.nodes.beads.rst b/docs/api/CodeEntropy.levels.nodes.beads.rst new file mode 100644 index 00000000..3a4b895f --- /dev/null +++ b/docs/api/CodeEntropy.levels.nodes.beads.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.nodes.beads module +===================================== + +.. automodule:: CodeEntropy.levels.nodes.beads + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.nodes.conformations.rst b/docs/api/CodeEntropy.levels.nodes.conformations.rst new file mode 100644 index 00000000..7bd29ddb --- /dev/null +++ b/docs/api/CodeEntropy.levels.nodes.conformations.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.nodes.conformations module +============================================= + +.. automodule:: CodeEntropy.levels.nodes.conformations + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.nodes.covariance.rst b/docs/api/CodeEntropy.levels.nodes.covariance.rst new file mode 100644 index 00000000..cee6c7da --- /dev/null +++ b/docs/api/CodeEntropy.levels.nodes.covariance.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.nodes.covariance module +========================================== + +.. automodule:: CodeEntropy.levels.nodes.covariance + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.nodes.detect_levels.rst b/docs/api/CodeEntropy.levels.nodes.detect_levels.rst new file mode 100644 index 00000000..058073eb --- /dev/null +++ b/docs/api/CodeEntropy.levels.nodes.detect_levels.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.nodes.detect\_levels module +============================================== + +.. automodule:: CodeEntropy.levels.nodes.detect_levels + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.nodes.detect_molecules.rst b/docs/api/CodeEntropy.levels.nodes.detect_molecules.rst new file mode 100644 index 00000000..14eb778c --- /dev/null +++ b/docs/api/CodeEntropy.levels.nodes.detect_molecules.rst @@ -0,0 +1,7 @@ +CodeEntropy.levels.nodes.detect\_molecules module +================================================= + +.. automodule:: CodeEntropy.levels.nodes.detect_molecules + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.levels.nodes.rst b/docs/api/CodeEntropy.levels.nodes.rst new file mode 100644 index 00000000..7ce5004f --- /dev/null +++ b/docs/api/CodeEntropy.levels.nodes.rst @@ -0,0 +1,20 @@ +CodeEntropy.levels.nodes package +================================ + +.. automodule:: CodeEntropy.levels.nodes + :members: + :show-inheritance: + :undoc-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.levels.nodes.accumulators + CodeEntropy.levels.nodes.beads + CodeEntropy.levels.nodes.conformations + CodeEntropy.levels.nodes.covariance + CodeEntropy.levels.nodes.detect_levels + CodeEntropy.levels.nodes.detect_molecules diff --git a/docs/api/CodeEntropy.levels.rst b/docs/api/CodeEntropy.levels.rst new file mode 100644 index 00000000..f3e6210c --- /dev/null +++ b/docs/api/CodeEntropy.levels.rst @@ -0,0 +1,30 @@ +CodeEntropy.levels package +========================== + +.. automodule:: CodeEntropy.levels + :members: + :show-inheritance: + :undoc-members: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.levels.nodes + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.levels.axes + CodeEntropy.levels.dihedrals + CodeEntropy.levels.forces + CodeEntropy.levels.frame_dag + CodeEntropy.levels.hierarchy + CodeEntropy.levels.level_dag + CodeEntropy.levels.linalg + CodeEntropy.levels.mda diff --git a/docs/api/CodeEntropy.molecules.grouping.rst b/docs/api/CodeEntropy.molecules.grouping.rst new file mode 100644 index 00000000..4fd9ebf5 --- /dev/null +++ b/docs/api/CodeEntropy.molecules.grouping.rst @@ -0,0 +1,7 @@ +CodeEntropy.molecules.grouping module +===================================== + +.. automodule:: CodeEntropy.molecules.grouping + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.molecules.rst b/docs/api/CodeEntropy.molecules.rst new file mode 100644 index 00000000..af25747e --- /dev/null +++ b/docs/api/CodeEntropy.molecules.rst @@ -0,0 +1,15 @@ +CodeEntropy.molecules package +============================= + +.. automodule:: CodeEntropy.molecules + :members: + :show-inheritance: + :undoc-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.molecules.grouping diff --git a/docs/api/CodeEntropy.results.reporter.rst b/docs/api/CodeEntropy.results.reporter.rst new file mode 100644 index 00000000..d8a56fd8 --- /dev/null +++ b/docs/api/CodeEntropy.results.reporter.rst @@ -0,0 +1,7 @@ +CodeEntropy.results.reporter module +=================================== + +.. automodule:: CodeEntropy.results.reporter + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/api/CodeEntropy.results.rst b/docs/api/CodeEntropy.results.rst new file mode 100644 index 00000000..40d4eee2 --- /dev/null +++ b/docs/api/CodeEntropy.results.rst @@ -0,0 +1,15 @@ +CodeEntropy.results package +=========================== + +.. automodule:: CodeEntropy.results + :members: + :show-inheritance: + :undoc-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.results.reporter diff --git a/docs/api/CodeEntropy.rst b/docs/api/CodeEntropy.rst new file mode 100644 index 00000000..1e9b3bdc --- /dev/null +++ b/docs/api/CodeEntropy.rst @@ -0,0 +1,28 @@ +CodeEntropy package +=================== + +.. automodule:: CodeEntropy + :members: + :show-inheritance: + :undoc-members: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.config + CodeEntropy.core + CodeEntropy.entropy + CodeEntropy.levels + CodeEntropy.molecules + CodeEntropy.results + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + CodeEntropy.cli diff --git a/docs/api/modules.rst b/docs/api/modules.rst new file mode 100644 index 00000000..680d032d --- /dev/null +++ b/docs/api/modules.rst @@ -0,0 +1,7 @@ +CodeEntropy +=========== + +.. toctree:: + :maxdepth: 4 + + CodeEntropy diff --git a/docs/conf.py b/docs/conf.py index cf51cf86..090c5162 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,29 +4,25 @@ # # This file does only contain a selection of the most common options. For a # full list see the documentation: -# http://www.sphinx-doc.org/en/stable/config +# https://www.sphinx-doc.org/en/stable/usage/configuration.html # -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. - -# Incase the project was not installed import os import sys import time -sys.path.insert(0, os.path.abspath("..")) - -# import CodeEntropy +# Ensure the *repo root* is on sys.path so autodoc imports the local package. +# This works whether conf.py is in docs/ or docs/source/. +DOCS_DIR = os.path.abspath(os.path.dirname(__file__)) +REPO_ROOT = os.path.abspath(os.path.join(DOCS_DIR, "..")) +sys.path.insert(0, REPO_ROOT) # -- Project information ----------------------------------------------------- - project = "CodeEntropy" copyright_first_year = "2022" copyright_owners = "CCPBioSim" author = "CCPBioSim" + current_year = str(time.localtime().tm_year) copyright_year_string = ( current_year @@ -35,21 +31,10 @@ ) copyright = f"{copyright_year_string}, {copyright_owners}. All rights reserved" -# The short X.Y version version = "" -# The full version, including alpha/beta/rc tags release = "" - # -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ "sphinx.ext.autosummary", "sphinx.ext.autodoc", @@ -62,98 +47,46 @@ "sphinx_copybutton", ] +# Autosummary (API stubs) autosummary_generate = True -napoleon_google_docstring = False -napoleon_use_param = False + +# Napoleon: Google-style docstrings +napoleon_google_docstring = True +napoleon_numpy_docstring = False + +# Render Google "Args:" into :param: fields (recommended) +napoleon_use_param = True +napoleon_use_rtype = True napoleon_use_ivar = True -# Add any paths that contain templates here, relative to this directory. +# (Optional) If some modules have optional heavy deps, you can mock them here: +# autodoc_mock_imports = ["MDAnalysis"] + templates_path = ["_templates"] -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] source_suffix = ".rst" - -# The master toctree document. master_doc = "index" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. language = "en" -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path . exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -# The name of the Pygments (syntax highlighting) style to use. pygments_style = "default" - # -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# html_theme = "furo" html_theme_options = { "light_logo": "images/biosim-codeentropy_logo_light.png", "dark_logo": "images/biosim-codeentropy_logo_dark.png", } -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - # -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. htmlhelp_basename = "CodeEntropydoc" - # -- Options for LaTeX output ------------------------------------------------ +latex_elements = {} -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, @@ -164,19 +97,10 @@ ), ] - # -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). man_pages = [(master_doc, "CodeEntropy", "CodeEntropy Documentation", [author], 1)] - # -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) texinfo_documents = [ ( master_doc, diff --git a/docs/faq.rst b/docs/faq.rst index 7ef18da6..88b6d94b 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -11,7 +11,7 @@ This is especially true at the residue level. For example in a lysozyme system, the residue level contains the largest force and torque covariance matrices because at this level we have the largest number of beads (which is equal to the number of residues in a protein) compared to the molecule level (3 beads) and united-atom level (~10 beads per amino acid). What do I do if there is an error from MDAnalysis not recognising the file type? -------------------------------------------------------------------------------- +-------------------------------------------------------------------------------- Use the file_format option. The MDAnalysis documentation has a list of acceptable formats: https://userguide.mdanalysis.org/1.1.1/formats/index.html#id1. diff --git a/docs/index.rst b/docs/index.rst index 3ba86d78..2e1bc5b4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,7 +15,7 @@ This code is a complete and generally applicable set of tools for computing entr :caption: Contents: getting_started - api + api/modules science faq developer_guide diff --git a/pyproject.toml b/pyproject.toml index 4d8ba438..0e2a903a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -65,7 +65,8 @@ testing = [ pre-commit = [ "pre-commit>=4.5,<5.0", "ruff>=0.15,<0.16", - "pylint>=4.0,<5.0" + "pylint>=4.0,<5.0", + "rstcheck>=6.2,<7.0" ] docs = [ "sphinx>=9.1,<9.2",