From d5ad86bbf5b05ac843aab72f395fac6a6fd09c6a Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Tue, 3 Nov 2026 16:04:18 +0000 Subject: [PATCH 1/5] chore(deps): replace furo and the old docs extensions with ccpbiosim-sphinx-theme and sphinx-autoapi --- pyproject.toml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index a102bf8..fedadef 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,12 +45,8 @@ pre-commit = [ ] docs = [ "sphinx>=9,<10", - "nbsphinx>=0.9,<1.0", - "sphinx-rtd-theme>=3,<3.2", - "sphinx-copybutton>=0.5,<1.0", - "sphinxcontrib-contentui>=0.2,<1.0", - "sphinxcontrib-details-directive>=0.1,<1.0", - "furo>=2025.0,<2026.0", + "sphinx-autoapi>=3.8,<4.0", + "ccpbiosim-sphinx-theme>=1.3.2,<2.0", "markupsafe>=3.0,<4.0", "myst-parser", ] From 87965cc63a016d509a72a6cf84d72d304a852ea5 Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Tue, 3 Nov 2026 16:05:02 +0000 Subject: [PATCH 2/5] docs: fix the score_pdb_map docstring so its arguments render --- prepmd/point_cloud.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/prepmd/point_cloud.py b/prepmd/point_cloud.py index 116d0d4..d65a47b 100644 --- a/prepmd/point_cloud.py +++ b/prepmd/point_cloud.py @@ -44,11 +44,11 @@ def score_pdb_map(pdb, em_map, contour_level): similarity based on the error in an alignment between two point clouds. Args: - pdb - path to a pdb file, a string - em_map - path to an an em map file for the same structure as that pdb, - a string. + pdb: path to a pdb file, a string. + em_map: path to an em map file for the same structure as that pdb, + a string. contour_level: density above which to add a point to the point cloud, - a float. + a float. Returns: the error, a float From 1011b693b67b6e51bfb0dd3ed178978ca81b6468 Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Tue, 3 Nov 2026 16:05:59 +0000 Subject: [PATCH 3/5] feat(docs): set the ccpbiosim sphinx theme and generate the API reference with sphinx-autoapi --- .gitignore | 4 +- docs/source/api/modules.rst | 7 -- docs/source/api/prepmd.lib.rst | 29 ------- docs/source/api/prepmd.rst | 133 --------------------------------- docs/source/conf.py | 78 +++++++++---------- 5 files changed, 43 insertions(+), 208 deletions(-) delete mode 100644 docs/source/api/modules.rst delete mode 100644 docs/source/api/prepmd.lib.rst delete mode 100644 docs/source/api/prepmd.rst diff --git a/.gitignore b/.gitignore index c5bccaf..b707344 100644 --- a/.gitignore +++ b/.gitignore @@ -69,7 +69,9 @@ instance/ .scrapy # Sphinx documentation -docs/_build/ +docs/build/ +docs/source/reference/ +docs/source/api/ # PyBuilder .pybuilder/ diff --git a/docs/source/api/modules.rst b/docs/source/api/modules.rst deleted file mode 100644 index 4e5a5a3..0000000 --- a/docs/source/api/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -prepmd -====== - -.. toctree:: - :maxdepth: 4 - - prepmd diff --git a/docs/source/api/prepmd.lib.rst b/docs/source/api/prepmd.lib.rst deleted file mode 100644 index 36fb983..0000000 --- a/docs/source/api/prepmd.lib.rst +++ /dev/null @@ -1,29 +0,0 @@ -prepmd.lib package -================== - -Submodules ----------- - -prepmd.lib.icp module ---------------------- - -.. automodule:: prepmd.lib.icp - :members: - :show-inheritance: - :undoc-members: - -prepmd.lib.mdaCIF module ------------------------- - -.. automodule:: prepmd.lib.mdaCIF - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: prepmd.lib - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/source/api/prepmd.rst b/docs/source/api/prepmd.rst deleted file mode 100644 index 7ee040f..0000000 --- a/docs/source/api/prepmd.rst +++ /dev/null @@ -1,133 +0,0 @@ -prepmd package -============== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - prepmd.lib - -Submodules ----------- - -prepmd.add\_modeller\_license module ------------------------------------- - -.. automodule:: prepmd.add_modeller_license - :members: - :show-inheritance: - :undoc-members: - -prepmd.align\_together module ------------------------------ - -.. automodule:: prepmd.align_together - :members: - :show-inheritance: - :undoc-members: - -prepmd.analysis module ----------------------- - -.. automodule:: prepmd.analysis - :members: - :show-inheritance: - :undoc-members: - -prepmd.download module ----------------------- - -.. automodule:: prepmd.download - :members: - :show-inheritance: - :undoc-members: - -prepmd.fix module ------------------ - -.. automodule:: prepmd.fix - :members: - :show-inheritance: - :undoc-members: - -prepmd.get\_residues module ---------------------------- - -.. automodule:: prepmd.get_residues - :members: - :show-inheritance: - :undoc-members: - -prepmd.ligand module --------------------- - -.. automodule:: prepmd.ligand - :members: - :show-inheritance: - :undoc-members: - -prepmd.metadynamics module --------------------------- - -.. automodule:: prepmd.metadynamics - :members: - :show-inheritance: - :undoc-members: - -prepmd.model module -------------------- - -.. automodule:: prepmd.model - :members: - :show-inheritance: - :undoc-members: - -prepmd.pdb2pqr module ---------------------- - -.. automodule:: prepmd.pdb2pqr - :members: - :show-inheritance: - :undoc-members: - -prepmd.point\_cloud module --------------------------- - -.. automodule:: prepmd.point_cloud - :members: - :show-inheritance: - :undoc-members: - -prepmd.prep module ------------------- - -.. automodule:: prepmd.prep - :members: - :show-inheritance: - :undoc-members: - -prepmd.run module ------------------ - -.. automodule:: prepmd.run - :members: - :show-inheritance: - :undoc-members: - -prepmd.util module ------------------- - -.. automodule:: prepmd.util - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: prepmd - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/source/conf.py b/docs/source/conf.py index b510a07..937f867 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,76 +1,78 @@ # Configuration file for the Sphinx documentation builder. +import importlib.metadata + # -- Project information ----------------------------------------------------- project = "prepmd" copyright = "2026, CCPBioSim" author = "CCPBioSim" -version = "" -release = "" +release = importlib.metadata.version("prepmd") # -- General configuration --------------------------------------------------- extensions = [ - "sphinx.ext.autosummary", - "sphinx.ext.autodoc", "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx.ext.extlinks", - "nbsphinx", - "sphinx_copybutton", "myst_parser", + "autoapi.extension", ] -autosummary_generate = True - -autodoc_member_order = "bysource" -autodoc_typehints = "description" - templates_path = ["_templates"] exclude_patterns = [] -# -- Autosummary / autodoc --------------------------------------------------- +# -- Napoleon docstring settings -------------------------------------------- -autosummary_generate = True +napoleon_google_docstring = True +napoleon_numpy_docstring = False +napoleon_use_param = True +napoleon_use_ivar = True -autosummary_mock_imports = [ - "openff", - "openff.toolkit", - "sklearn", +# -- API reference generated from the source by sphinx-autoapi -------------- + +autoapi_dirs = ["../../prepmd"] +autoapi_root = "reference" +autoapi_add_toctree_entry = False +autoapi_member_order = "groupwise" +# Include the __init__ docstring, where the constructor arguments are documented +autoapi_python_class_content = "both" +autoapi_options = [ + "members", + "undoc-members", + "show-inheritance", + "show-module-summary", ] -autodoc_member_order = "bysource" +# Show type hints in the parameter list rather than the signature autodoc_typehints = "description" +add_module_names = False +python_maximum_signature_line_length = 88 -autodoc_mock_imports = [ - "openff", - "openff.toolkit", - "sklearn", -] -# -- Napoleon docstring settings -------------------------------------------- +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -napoleon_google_docstring = True -napoleon_numpy_docstring = False -napoleon_use_param = False -napoleon_use_ivar = True +html_theme = "ccpbiosim_sphinx_theme" +html_context = {"github_repo": "prepmd"} +html_static_path = ["_static"] -templates_path = ["_templates"] -exclude_patterns = [] +# Some module variables are assigned twice, such as a default followed by a +# fallback in an except block. Document each name only once. +_documented = set() -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = "furo" +def skip_repeated_members(app, what, name, obj, skip, options): + if name in _documented: + return True + _documented.add(name) + return skip -html_theme_options = { - "light_logo": "logos/prepmd-logo-black.svg", - "dark_logo": "logos/prepmd-logo-white.svg", -} -html_static_path = ["_static"] +def setup(app): + app.connect("autoapi-skip-member", skip_repeated_members) From 76965046b36abe29a2cde114d0fc53159070f0aa Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Tue, 3 Nov 2026 16:06:31 +0000 Subject: [PATCH 4/5] feat(docs): add the banner, quick start and section cards to the home page --- docs/source/index.rst | 106 +++++++++++++++++++++++++++++++++++------- 1 file changed, 89 insertions(+), 17 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 3cc401f..b9b8a67 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,23 +1,95 @@ -.. prepmd documentation master file, created by - sphinx-quickstart on Mon Jun 8 11:38:38 2026. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +:html_theme.sidebar_secondary.remove: -prepmd documentation -==================== +prepmd +====== -A utility to automatically prepare structures from the PDB for molecular dynamics simulation and perform minimisations and simple MD simulations. Source: https://github.com/CCPBioSim/prepmd +.. ccpbiosim-hero:: + :logo-light: _static/logos/prepmd-logo-black.svg + :logo-dark: _static/logos/prepmd-logo-white.svg + :logo-alt: prepmd logo + :tagline: prepmd + :button: Installation | Get started + :github: CCPBioSim/prepmd + Automatically prepare PDB and mmCIF structures for molecular dynamics simulations + +A utility to automatically prepare structures from the PDB for molecular dynamics +simulation and perform minimisations and simple MD simulations. + +Quick start +----------- + +.. tab-set:: + + .. tab-item:: Install + + .. code-block:: bash + + conda install -c ccpbiosim prepmd + + .. tab-item:: Prepare + + .. code-block:: bash + + prepmd 6xov 6xov_processed.cif + + .. tab-item:: Run + + .. code-block:: bash + + runmd 6xov_processed.cif --traj_out traj.xtc --md_steps 5000 + +Explore the documentation +------------------------- + +.. grid:: 1 2 2 3 + :gutter: 3 + + .. grid-item-card:: 📦 Installation + :link: Installation + :link-type: doc + + Install prepmd with Conda and add a MODELLER licence. + + .. grid-item-card:: 🚀 Quickstart + :link: Quickstart + :link-type: doc + + Prepare a structure and run a short simulation. + + .. grid-item-card:: 🧬 Prepare Structures + :link: Prep-Structure + :link-type: doc + + Prepare structure files for simulation with prepmd. + + .. grid-item-card:: ⚙️ Run Simulations + :link: Run-with-runmd + :link-type: doc + + Run MD simulations with runmd. + + .. grid-item-card:: 🐍 Python API + :link: Python-API + :link-type: doc + + Use prepmd from Python. + + .. grid-item-card:: 📖 API Reference + :link: reference/prepmd/index + :link-type: doc + + Reference for the prepmd package. .. toctree:: :maxdepth: 2 - :caption: Contents: - - Installation - Quickstart - Prep-Structure - Run-with-runmd - Whats-next - Python-API - Developer-Notes - api/modules + :hidden: + + Installation + Quickstart + Prepare + Run + What Next + Python API + Developer Notes + API Reference From c22b086c802e3f5109c0ed3f8d2f4a23438e299a Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Tue, 3 Nov 2026 16:28:47 +0000 Subject: [PATCH 5/5] chore(deps): upgrade `ccpbiosim-sphinx-theme` to v1.3.3 to use more section --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index fedadef..8943f0d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -46,7 +46,7 @@ pre-commit = [ docs = [ "sphinx>=9,<10", "sphinx-autoapi>=3.8,<4.0", - "ccpbiosim-sphinx-theme>=1.3.2,<2.0", + "ccpbiosim-sphinx-theme>=1.3.3,<2.0", "markupsafe>=3.0,<4.0", "myst-parser", ]