Add api docs

.readthedocs.yaml

@@ -15,7 +15,7 @@ sphinx:
    fail_on_warning: true
 
 conda:
-  environment: environment.yml
+  environment: docs/environment.yaml
 
 python:
   # Install our python package before building the docs so setuptools-scm generates the version for RTD to find.

README.md

@@ -3,6 +3,7 @@
 [![Logo](https://img.shields.io/badge/OSMF-OpenFreeEnergy-%23002f4a)](https://openfree.energy/)
 [![CI](https://github.com/OpenFreeEnergy/openfe_analysis/actions/workflows/ci.yaml/badge.svg)](https://github.com/OpenFreeEnergy/openfe_analysis/actions/workflows/ci.yaml)
 [![Coverage](https://codecov.io/gh/OpenFreeEnergy/openfe_analysis/graph/badge.svg?token=krb231ftki)](https://codecov.io/gh/OpenFreeEnergy/openfe_analysis)
+[![documentation](https://readthedocs.org/projects/openfe_analysis/badge/?version=stable)](https://openfe_analysis.openfree.energy/en/stable/?badge=stable)
 [![Powered by MDAnalysis](https://img.shields.io/badge/powered%20by-MDAnalysis-orange.svg?logoWidth=16&logo=data:image/x-icon;base64,AAABAAEAEBAAAAEAIAAoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJD+XwCY/fEAkf3uAJf97wGT/a+HfHaoiIWE7n9/f+6Hh4fvgICAjwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACT/yYAlP//AJ///wCg//8JjvOchXly1oaGhv+Ghob/j4+P/39/f3IAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJH8aQCY/8wAkv2kfY+elJ6al/yVlZX7iIiI8H9/f7h/f38UAAAAAAAAAAAAAAAAAAAAAAAAAAB/f38egYF/noqAebF8gYaagnx3oFpUUtZpaWr/WFhY8zo6OmT///8BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgICAn46Ojv+Hh4b/jouJ/4iGhfcAAADnAAAA/wAAAP8AAADIAAAAAwCj/zIAnf2VAJD/PAAAAAAAAAAAAAAAAICAgNGHh4f/gICA/4SEhP+Xl5f/AwMD/wAAAP8AAAD/AAAA/wAAAB8Aov9/ALr//wCS/Z0AAAAAAAAAAAAAAACBgYGOjo6O/4mJif+Pj4//iYmJ/wAAAOAAAAD+AAAA/wAAAP8AAABhAP7+FgCi/38Axf4fAAAAAAAAAAAAAAAAiIiID4GBgYKCgoKogoB+fYSEgZhgYGDZXl5e/m9vb/9ISEjpEBAQxw8AAFQAAAAAAAAANQAAADcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAjo6Mb5iYmP+cnJz/jY2N95CQkO4pKSn/AAAA7gAAAP0AAAD7AAAAhgAAAAEAAAAAAAAAAACL/gsAkv2uAJX/QQAAAAB9fX3egoKC/4CAgP+NjY3/c3Nz+wAAAP8AAAD/AAAA/wAAAPUAAAAcAAAAAAAAAAAAnP4NAJL9rgCR/0YAAAAAfX19w4ODg/98fHz/i4uL/4qKivwAAAD/AAAA/wAAAP8AAAD1AAAAGwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALGxsVyqqqr/mpqa/6mpqf9KSUn/AAAA5QAAAPkAAAD5AAAAhQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADkUFBSuZ2dn/3V1df8uLi7bAAAATgBGfyQAAAA2AAAAMwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB0AAADoAAAA/wAAAP8AAAD/AAAAWgC3/2AAnv3eAJ/+dgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA9AAAA/wAAAP8AAAD/AAAA/wAKDzEAnP3WAKn//wCS/OgAf/8MAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIQAAANwAAADtAAAA7QAAAMAAABUMAJn9gwCe/e0Aj/2LAP//AQAAAAAAAAAA)](https://www.mdanalysis.org)
 
 ## Quickstart

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -v -W --keep-going
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,11 @@
+API Documentation
+=================
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   openfe_analysis.reader
+   openfe_analysis.transformations
+   openfe_analysis.rmsd
+   openfe_analysis.utils

docs/conf.py

@@ -0,0 +1,66 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/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.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../"))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "openfe analysis"
+copyright = "2026, The OpenFE Development Team"
+author = "The OpenFE Development Team"
+
+# -- General configuration ---------------------------------------------------
+
+# 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.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+]
+
+autoclass_content = "both"
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": True,
+}
+autosummary_generate = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# 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.
+# 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"]
+
+autodoc_mock_imports = [
+    "MDAnalysis",
+]
+
+
+# -- 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"

docs/environment.yaml

@@ -0,0 +1,9 @@
+name: openfe_analysis-docs
+channels:
+  - https://conda.anaconda.org/jaimergp/label/unsupported-cudatoolkit-shim
+  - https://conda.anaconda.org/conda-forge
+dependencies:
+- openff-units
+- python=3.12
+- sphinx
+- furo

docs/index.rst

@@ -0,0 +1,15 @@
+.. template taken from SciPy who took it from Pandas (keep the chain going)
+
+.. module:: openfe_analysis
+
+==========================================
+Welcome to OpenFE Analysis' documentation!
+==========================================
+
+The **OpenFE Analysis** toolkit provides a free and open-source framework for analyzing alchemical free energy calculations.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   api

src/openfe_analysis/rmsd.py

@@ -7,7 +7,6 @@
 import numpy as np
 import tqdm
 from MDAnalysis.analysis import rms
-from MDAnalysis.lib.mdamath import make_whole
 from MDAnalysis.transformations import unwrap
 from numpy import typing as npt
 
@@ -42,20 +41,22 @@ def make_Universe(top: pathlib.Path, trj: nc.Dataset, state: int) -> mda.Univers
     Notes
     -----
     Identifies two AtomGroups:
-    - protein, defined as having standard amino acid names, then filtered
-      down to CA
-    - ligand, defined as resname UNK
+
+    - Protein, defined as having standard amino acid names, then filtered down to CA
+    - Ligand, defined as "resname UNK"
 
     Depending on whether a protein is present, a sequence of trajectory
     transformations is applied:
 
     If a protein is present:
+
     - Unwraps protein and ligand atom to be made whole
     - Shifts protein chains and the ligand to the image closest to the first
       protein chain (:class:`ClosestImageShift`)
     - Aligns the entire system to minimise the protein RMSD (:class:`Aligner`)
 
     If only a ligand is present:
+
     - Prevents the ligand from jumping between periodic images
     - Aligns the ligand to minimize its RMSD
     """
@@ -125,16 +126,17 @@ def gather_rms_data(
     Notes
     -----
     For each thermodynamic state (lambda), this function:
-      - Loads the trajectory using ``FEReader``
-      - Applies standard PBC-handling and alignment transformations
-      - Computes protein and ligand structural metrics over time
+
+    - Loads the trajectory using ``FEReader``
+    - Applies standard PBC-handling and alignment transformations
+    - Computes protein and ligand structural metrics over time
 
     The following analyses are produced per state:
-      - 1D protein CA RMSD time series
-      - 1D ligand RMSD time series
-      - Ligand center-of-mass displacement from its initial position
-        (``ligand_wander``)
-      - Flattened 2D protein RMSD matrix (pairwise RMSD between frames)
+
+    - 1D protein CA RMSD time series
+    - 1D ligand RMSD time series
+    - Ligand center-of-mass displacement from its initial position (``ligand_wander``)
+    - Flattened 2D protein RMSD matrix (pairwise RMSD between frames)
     """
     output = {
         "protein_RMSD": [],

src/openfe_analysis/transformations.py

@@ -70,8 +70,7 @@ class ClosestImageShift(TransformationBase):
     Notes
     -----
     - Works for any box type (triclinic or orthorhombic).
-    - Inspired from:
-    https://github.com/wolberlab/OpenMMDL/blob/main/openmmdl/openmmdl_simulation/scripts/post_md_conversions.py
+    - Inspired from: https://github.com/wolberlab/OpenMMDL/blob/main/openmmdl/openmmdl_simulation/scripts/post_md_conversions.py
     """
 
     def __init__(self, reference: mda.AtomGroup, targets: list[mda.AtomGroup]):