MDAnalysis documentation style (#1)

* Docs are now generated using the MDAnalysis Sphinx theme * A github action now handles deployment of docs to pages * Added references
MDAnalysis · Aug 22, 2023 · 939373a · 939373a
1 parent b34fe3a
commit 939373a
Show file tree

Hide file tree

Showing 19 changed files with 136 additions and 127 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,62 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: "${{ github.ref }}-${{ github.head_ref }}"
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+jobs:
+  docs:
+    if: "github.repository == 'MDAnalysis/mdaencore'"
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0         
+
+    - name: setup_miniconda
+      uses: conda-incubator/setup-miniconda@v2
+      with:
+        python-version: 3.11
+        environment-file: docs/requirements.yaml
+        auto-update-conda: true
+        channel-priority: flexible
+        channels: conda-forge
+        miniforge-variant: Mambaforge
+        use-mamba: true
+
+    - name: Build and install package
+      run: |
+          mamba env update -n test -f devtools/conda-envs/test_env.yaml
+          python setup.py build_ext -i
+          python -m pip install -e .
+
+    - name: build docs
+      run: |
+        cd docs && sphinx-build -b html source build
+
+    - name: deploy docs
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.event_name != 'pull_request'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/build
+        user_name: 'github-actions'
+        user_email: 'github-action@users.noreply.github.com'
+
+    - uses: actions/upload-artifact@v3
+      if: github.event_name == 'pull_request'
+      with:
+        name: pr_docs
+        path: ./docs/build/
diff --git a/docs/requirements.yaml b/docs/requirements.yaml
@@ -1,14 +1,19 @@
 name: mdaencore-docs
 channels:
+    - default
+    - conda-forge
 dependencies:
     # Base depends
-  - python
-  - pip
+    - python
+    - pip
 
-  - sphinx<7.0
+    - sphinxcontrib-bibtex
 
-  - sphinx_rtd_theme
-
-    # Pip-only installs
-  #- pip:
+    - numpy
+    - scipy
+    - MDAnalysis
+    - MDAnalysisTests
+    - pytest
 
+    - pip:
+        - mdanalysis-sphinx-theme
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -46,16 +46,23 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinxcontrib.bibtex',
     'sphinx.ext.autosummary',
     'sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
+    'mdanalysis_sphinx_theme',
     'sphinx.ext.extlinks',
 ]
 
+bibtex_bibfiles = ['references.bib']
+
 autosummary_generate = True
+autodoc_mock_imports = [
+    'mdaencore.tests',
+]
 napoleon_google_docstring = False
 napoleon_use_param = False
 napoleon_use_ivar = True
@@ -93,18 +100,17 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'mdanalysis_sphinx_theme'
 
 # 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 = {}
+html_theme_options = {'mda_official': True}
 
 # 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.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -9,11 +9,13 @@ Welcome to mdaencore's documentation!
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+   :hidden:
 
    getting_started
    api
 
 
+The `mdaencore` MDAKit moves the functionality of integrated ENCORE module out of the MDAnalysis core library, thereby deprecating it in MDAnalysis release 2.7.0 with a planned removal in release 3.0.0.
 
 Indices and tables
 ==================

diff --git a/docs/source/references.bib b/docs/source/references.bib
@@ -0,0 +1,25 @@
+@article{LindorffLarsen2009,
+    doi = {10.1371/journal.pone.0004203},
+    author = {Lindorff-Larsen, Kresten AND Ferkinghoff-Borg, Jesper},
+    journal = {PLOS ONE},
+    publisher = {Public Library of Science},
+    title = {Similarity Measures for Protein Ensembles},
+    year = {2009},
+    month = {01},
+    volume = {4},
+    pages = {1-13},
+    number = {1}
+}
+
+@article{Tiberti2015,
+    doi = {10.1371/journal.pcbi.1004415},
+    author = {Tiberti, Matteo AND Papaleo, Elena AND Bengtsen, Tone AND Boomsma, Wouter AND Lindorff-Larsen, Kresten},
+    journal = {PLOS Computational Biology},
+    publisher = {Public Library of Science},
+    title = {ENCORE: Software for Quantitative Ensemble Comparison},
+    year = {2015},
+    month = {10},
+    volume = {11},
+    pages = {1-16},
+    number = {10}
+}
diff --git a/mdaencore/bootstrap.py b/mdaencore/bootstrap.py
@@ -21,7 +21,7 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 """
-bootstrap procedures --- :mod:`MDAnalysis.analysis.ensemble.bootstrap`
+bootstrap procedures --- :mod:`mdaencore.bootstrap`
 ======================================================================
 
 
@@ -30,8 +30,6 @@
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
-
 """
 import numpy as np
 import logging

diff --git a/mdaencore/clustering/ClusterCollection.py b/mdaencore/clustering/ClusterCollection.py
@@ -21,16 +21,14 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 """
-Cluster representation --- :mod:`MDAnalysis.analysis.encore.clustering.ClusterCollection`
+Cluster representation --- :mod:`mdaencore.clustering.ClusterCollection`
 =========================================================================================
 
 The module contains the Cluster and ClusterCollection classes which are
 designed to store results from clustering algorithms.
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
-
 """
 import numpy as np
 

diff --git a/mdaencore/clustering/ClusteringMethod.py b/mdaencore/clustering/ClusteringMethod.py
@@ -21,7 +21,7 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 """
-clustering frontend --- :mod:`MDAnalysis.analysis.encore.clustering.ClusteringMethod`
+clustering frontend --- :mod:`mdaencore.clustering.ClusteringMethod`
 =====================================================================================
 
 The module defines classes for interfacing to various clustering algorithms.
@@ -30,8 +30,6 @@
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
-
 """
 import numpy as np
 import warnings

diff --git a/mdaencore/clustering/__init__.py b/mdaencore/clustering/__init__.py
@@ -20,6 +20,11 @@
 # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
+
+"""\
+This package contains modules for performing clustering.
+"""
+
 from . import ClusteringMethod
 from . import ClusterCollection
 

diff --git a/mdaencore/clustering/cluster.py b/mdaencore/clustering/cluster.py
@@ -21,16 +21,14 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 """
-clustering frontend --- :mod:`MDAnalysis.analysis.encore.clustering.cluster`
+clustering frontend --- :mod:`mdaencore.clustering.cluster`
 ============================================================================
 
 The module defines a function serving as front-end for various clustering
 algorithms, wrapping them to allow them to be used interchangably.
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
-
 """
 import numpy as np
 from ..utils import ParallelCalculation, merge_universes

diff --git a/mdaencore/confdistmatrix.py b/mdaencore/confdistmatrix.py
@@ -21,7 +21,7 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 """
-Distance Matrix calculation --- :mod:`MDAnalysis.analysis.ensemble.confdistmatrix`
+Distance Matrix calculation --- :mod:`mdaencore.confdistmatrix`
 ==================================================================================
 
 
@@ -32,8 +32,6 @@ class to compute an RMSD matrix in such a way is also available.
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
-
 """
 from joblib import Parallel, delayed
 import numpy as np

diff --git a/mdaencore/covariance.py b/mdaencore/covariance.py
@@ -29,7 +29,6 @@
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
 """
 import numpy as np
 

diff --git a/mdaencore/cutils.pyx b/mdaencore/cutils.pyx
@@ -27,7 +27,6 @@ Mixed Cython utils for ENCORE
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
 """
 
 

diff --git a/mdaencore/dimensionality_reduction/DimensionalityReductionMethod.py b/mdaencore/dimensionality_reduction/DimensionalityReductionMethod.py
@@ -21,7 +21,7 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 """
-dimensionality reduction frontend --- :mod:`MDAnalysis.analysis.encore.clustering.DimensionalityReductionMethod`
+dimensionality reduction frontend --- :mod:`mdaencore.clustering.DimensionalityReductionMethod`
 ================================================================================================================
 
 The module defines classes for interfacing to various dimensionality reduction
@@ -30,8 +30,6 @@
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
-
 """
 import logging
 import warnings

diff --git a/mdaencore/dimensionality_reduction/reduce_dimensionality.py b/mdaencore/dimensionality_reduction/reduce_dimensionality.py
@@ -21,16 +21,14 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 """
-dimensionality reduction frontend --- :mod:`MDAnalysis.analysis.encore.dimensionality_reduction.reduce_dimensionality`
+dimensionality reduction frontend --- :mod:`mdaencore.dimensionality_reduction.reduce_dimensionality`
 ======================================================================================================================
 
 The module defines a function serving as front-end for various dimensionality
 reduction algorithms, wrapping them to allow them to be used interchangably.
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
-
 """
 import numpy as np
 from ..confdistmatrix import get_distance_matrix

diff --git a/mdaencore/similarity.py b/mdaencore/similarity.py
@@ -22,13 +22,11 @@
 #
 """
 =================================================================================
-Ensemble Similarity Calculations --- :mod:`MDAnalysis.analysis.encore.similarity`
+Ensemble Similarity Calculations --- :mod:`mdaencore.similarity`
 =================================================================================
 
 :Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen
 
-.. versionadded:: 0.16.0
-
 The module contains implementations of similarity measures between protein
 ensembles described in :cite:p:`b-LindorffLarsen2009`. The implementation and
 examples are described in :cite:p:`b-Tiberti2015`.
@@ -54,17 +52,6 @@
 
 When using this module in published work please cite :cite:p:`b-Tiberti2015`.
 
-.. rubric:: References
-
-.. bibliography::
-    :filter: False
-    :style: MDA
-    :keyprefix: b-
-    :labelprefix: ᵇ
-
-    Tiberti2015
-    LindorffLarsen2009
-
 .. _Examples:
 Examples
 ========
@@ -140,7 +127,7 @@
 
 In addition to the quantitative similarity estimate, the dimensional reduction
 can easily be visualized, see the ``Example`` section in
-:mod:`MDAnalysis.analysis.encore.dimensionality_reduction.reduce_dimensionality`.
+:mod:`mdaencore.dimensionality_reduction.reduce_dimensionality`.
 Due to the stochastic nature of SPE, two identical ensembles will not
 necessarily result in an exactly 0 estimate of the similarity, but will be very
 close. For the same reason, calculating the similarity with the :func:`dres`
@@ -171,6 +158,15 @@
 
 .. All functions are included via automodule :members:.
 
+.. rubric:: References
+
+.. bibliography::
+    :filter: False
+    :keyprefix: b-
+    :labelprefix: ᵇ
+
+    Tiberti2015
+    LindorffLarsen2009
 """
 import warnings
 import logging
@@ -1353,7 +1349,7 @@ def dres(ensembles,
 
     In addition to the quantitative similarity estimate, the dimensional
     reduction can easily be visualized, see the ``Example`` section in
-    :mod:`MDAnalysis.analysis.encore.dimensionality_reduction.reduce_dimensionality``
+    :mod:`mdaencore.dimensionality_reduction.reduce_dimensionality``
 
     """