Switch to MDA rtd sphinx theme (#122)

Switch to official sphinx theme and maintenance doc tasks.

- Switch to mdanalysis-sphinx-theme.
- Fix broken links.
- Update docs README.
- Update docs dependencies.
- Rerun and check tutorials.

CHANGELOG.rst

@@ -1,6 +1,11 @@
 Membranecurvature CHANGELOG
 =============================
 
+W.I.P
+* Switch to mdanalysis-sphinx-theme and update docs (PR #122).
+* Comply with PEP518 (PR #119).
+* Drop support for Python 3.8 (PR #112).
+
 1.0.0 (03-11-2022)
 -------------------
 

docs/README.md

@@ -1,24 +1,35 @@
 # Compiling Membrane Curvature's Documentation
 
-The docs for this project are built with [Sphinx](http://www.sphinx-doc.org/en/master/).
-To compile the docs, first ensure that Sphinx and the ReadTheDocs theme are installed.
+The docs for this project are built with [Sphinx](http://www.sphinx-doc.org/en/master/) using the [mdanalysis-sphinx-theme](https://github.com/MDAnalysis/mdanalysis-sphinx-theme).
+To compile the docs, first ensure that:
 
+1. All necessary dependencies are installed.
+1. You are working in the `/docs` directory.
+
+## Installing dependencies
+
+### Via conda
+
+To install a new environment with conda to compile the documentation, run:
 
 ```bash
-conda install sphinx sphinx_rtd_theme 
+conda install sphinx mdanalysis-sphinx-theme 
 ```
 
+### Via pip
+
+Alternatively, to install all doc dependencies in your environment, run:
 
-Once installed, you can use the `Makefile` in this directory to compile static HTML pages by
 ```bash
-make html
+pip install -r requirements.txt
 ```
 
-The compiled docs will be in the `_build` directory and can be viewed by opening `index.html` (which may itself 
-be inside a directory called `html/` depending on what version of Sphinx is installed).
+## Compiling MembraneCurvature Sphinx docs
 
+Once all dependencies are installed, you can use the `Makefile` in this directory to compile static HTML pages with
 
-A configuration file for [Read The Docs](https://readthedocs.org/) (readthedocs.yaml) is included in the top level of the repository. To use Read the Docs to host your documentation, go to https://readthedocs.org/ and connect this repository. You may need to change your default branch to `main` under Advanced Settings for the project.
-
-If you would like to use Read The Docs with `autodoc` (included automatically) and your package has dependencies, you will need to include those dependencies in your documentation yaml file (`docs/requirements.yaml`).
+```bash
+make html
+```
 
+The compiled docs will be in the `_build` directory and can be viewed by opening `index.html`.

docs/conf.py

@@ -16,20 +16,19 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
-
+import datetime
 
 # -- Project information -----------------------------------------------------
 
 project = 'membrane_curvature'
-copyright = ("2021, Estefania Barreto-Ojeda. Project structure based on the "
-             "Computational Molecular Science Python Cookiecutter version 1.5")
-author = 'Estefania Barreto-Ojeda'
-
+now = datetime.datetime.now()
+copyright = f"2021-{now.year}, Estefania Barreto-Ojeda. Project structure based on the" \
+             "Computational Molecular Science Python Cookiecutter version 1.5"
+author = 'Estefania Barreto-Ojeda. '
 # The short X.Y version
-version = ''
+version = __import__('membrane_curvature').__version__
 # The full version, including alpha/beta/rc tags
-release = ''
-
+release = version
 
 # -- General configuration ---------------------------------------------------
 
@@ -51,8 +50,8 @@
     'sphinx.ext.autosectionlabel',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
-    'sphinx_rtd_theme',
-    'nbsphinx'
+    'mdanalysis_sphinx_theme',
+    'myst_nb'
 ]
 
 autosectionlabel_prefix_document = True
@@ -68,7 +67,7 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.ipynb']
 
 # The master toctree document.
 master_doc = 'index'
@@ -78,7 +77,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+# language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -94,13 +93,21 @@
 # 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 = {}
+extra_nav_links = {}
+extra_nav_links["MDAnalysis"] = "http://mdanalysis.org"
+extra_nav_links["User guide"] = "http://userguide.mdanalysis.org"
+extra_nav_links["MDAKits"] = "https://mdakits.mdanalysis.org/"
+
+html_theme_options = {
+    "mda_official": True,
+    "extra_nav_links": extra_nav_links,
+}
 
 # 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,

docs/getting_started.rst

@@ -5,4 +5,50 @@ The `MDAnalysis`_ **MembraneCurvature** is a Python toolkit to calculate membran
 molecular dynamics simulations. This tool enables the user to derive surfaces from `atoms` of 
 reference (contained in an `AtomGroup`) and calculate its associated mean and Gaussian curvature.
 
-.. _MDAnalysis: https://www.mdanalysis.org
+.. _MDAnalysis: https://www.mdanalysis.org
+
+
+Installation
+--------------
+
+The main dependency in MembraneCurvature is `MDAnalysis`_. You can find
+instructions to install the latest stable version of MDAnalysis via 
+`conda`_ in the `Installation Quick Start`_ page.
+
+MembraneCurvature is available via pip:
+
+.. code-block:: bash
+
+   pip install membrane-curvature
+
+To install from source:
+
+.. code-block:: bash
+
+   git clone https://github.com/MDAnalysis/membrane-curvature.git
+   cd membrane-curvature
+   conda env create -f devtools/conda-envs/environment.yaml
+   conda activate membrane-curvature
+   python setup.py install
+
+Some of the examples included in the MembraneCurvature documentation use test
+cases from `MDAnalysis Tests`_. To install the unit tests via conda:
+
+.. code-block:: bash
+
+   conda install -c conda-forge MDAnalysisTests
+
+or via pip:
+
+.. code-block:: bash
+
+   pip install --upgrade MDAnalysisTests
+
+
+
+.. _MDAnalysis: https://www.mdanalysis.org
+.. _`github.com/MDAnalysis/membrane_curvature`: https://github.com/MDAnalysis/membrane-curvature
+.. _`MDAnalysis Tests`: https://github.com/MDAnalysis/mdanalysis/wiki/UnitTests
+.. _`Installation Quick Start`: https://www.mdanalysis.org/pages/installation_quick_start/#installation-quick-start
+.. _`conda`: https://conda.io/en/latest/
+.. |MDAnalysis_version| replace:: 1.1.1

docs/requirements.txt

@@ -0,0 +1,13 @@
+numpy>=1.20.0
+mdanalysis>=2.0.0
+ipython
+pickleshare # ipython savefigs
+MDAnalysisTests
+MDAnalysisData
+networkx # LeafletFinder dependency
+tidynamics # MSD dependency
+mdanalysis-sphinx-theme>=1.3.0
+ipykernel
+myst-nb
+ipywidgets 
+nglview

docs/requirements.yaml

@@ -1,4 +1,4 @@
-name: docs
+name: mc_docs
 channels:
   - conda-forge
   - defaults
@@ -8,11 +8,16 @@ dependencies:
   - pip
   - numpy
   - MDAnalysis
+  - MDAnalysisData
+  - networkx # LeafletFinder dependency
+  - tidynamics # MSD dependency
   - ipython
   - MDAnalysisTests
-  - sphinx_rtd_theme
+  - mdanalysis-sphinx-theme>=1.3.0
     # Pip-only installs
   - pip:
-    - nbsphinx
+    - myst-nb
+    - ipykernel
+    - pickleshare # ipython savefigs
     - ipywidgets
     - nglview

docs/source/pages/Tutorials.rst

@@ -10,9 +10,11 @@ nice visualizatons covering different types of MD systems!
 
 You can find the list of available tutorials below:
 
+Membrane-only systems
+^^^^^^^^^^^^^^^^^^^^^^^
+
 .. toctree::
    :maxdepth: 1
-   :caption: Membrane-only systems
 
    Curvature_membrane-only_systems.ipynb
 
@@ -24,9 +26,11 @@ Martini_ force field [Marrink2007]_.
     :align: center
     :width: 300
 
+Membrane-protein systems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. toctree::
    :maxdepth: 1
-   :caption: Membrane-protein systems 
 
    Curvature_membrane_protein_nopr_all_atom.ipynb
 

docs/source/pages/Usage.rst

@@ -134,7 +134,7 @@ After you have preprocessed the trajectory, a typical usage of membrane curvatur
 More information on how to visualize the results of the MDAnalysis Membrane 
 Curvature tool can be found in the :ref:`visualization` page.
 
-.. _`blog post`: https://ojeda-e.github.io/blog/Considerations-curvature-MD-simulations-PartI/
+.. _`blog post`: https://ojeda-e.com/blog/2021/07/22/Considerations-curvature-MD-simulations-PartI.html
 
 .. _`MDAnalysisTests`: https://github.com/MDAnalysis/mdanalysis/wiki/UnitTests
 

membrane_curvature/curvature.py

@@ -1,5 +1,4 @@
 r"""
-.. role:: raw-math(raw) :format: latex html
 
 --------------------
 Curvature

membrane_curvature/surface.py

@@ -1,5 +1,4 @@
 r"""
-.. role:: raw-math(raw) :format: latex html
 
 --------------------
 Surface

pyproject.toml

@@ -51,7 +51,7 @@ tests = [
 docs = [
     "ipython",
     "MDAnalysisTests",
-    "sphinx_rtd_theme",
+    "mdanalysis-sphinx-theme",
     "nbsphinx",
     "ipywidgets",
     "nglview"