Tutorials overhaul (#150)

* fix warnings when loading pickled FP
* fix frame number being numpy int
* fix barcode plot when no missing interaction
* add residue display function
* add lig-prot MD tutorial
* add better protein-protein support in 3d plot
* add prot-prot MD tutorial
* add docking tutorial
* add PDB tutorial
* add advanced tutorial

.readthedocs.yml

@@ -10,4 +10,4 @@ python:
   - method: pip
     path: .
 conda:
-  environment: .binder/environment.yml
+  environment: environment.yml

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Added a `display_residues` function to quickly visualize the residues in a `Molecule`
+  object.
 - Added a `Complex3D` class for plotting interactions in 3D. Added the corresponding
   `Fingerprint.plot_3d` method to generate the plot directly from an FP object.
 - Added a `Barcode` class for plotting interactions. Added the corresponding

README.rst

@@ -6,8 +6,6 @@ ProLIF
 
     * - **Documentation**
       - |docs|
-    * - **Tutorials**
-      - |binder|
     * - **CI**
       - |tests| |codecov| |codeql|
     * - **Builds**
@@ -25,32 +23,36 @@ interaction fingerprints for complexes made of ligands, protein, DNA or RNA mole
 extracted from molecular dynamics trajectories, docking simulations and experimental
 structures.
 
-You can try it out prior to any installation on `Binder <https://mybinder.org/v2/gh/chemosim-lab/ProLIF/HEAD?filepath=docs%2Fnotebooks>`_.
-
 Documentation
 -------------
 
-The installation instructions, documentation and tutorials can be found online on `ReadTheDocs <https://prolif.readthedocs.io/en/latest/>`_.
+The installation instructions, documentation and tutorials can be found online on
+`ReadTheDocs <https://prolif.readthedocs.io>`_.
 
 Issues
 ------
 
-If you have found a bug, please open an issue on the `GitHub Issues <https://github.com/chemosim-lab/ProLIF/issues>`_ page.
+If you have found a bug, please open an issue on the
+`GitHub Issues <https://github.com/chemosim-lab/ProLIF/issues>`_ page.
 
 Discussion
 ----------
 
-If you have questions on how to use ProLIF, or if you want to give feedback or share ideas and new features, please head to the `GitHub Discussions <https://github.com/chemosim-lab/ProLIF/discussions>`_ page.
+If you have questions on how to use ProLIF, or if you want to give feedback or share
+ideas and new features, please head to the
+`GitHub Discussions <https://github.com/chemosim-lab/ProLIF/discussions>`_ page.
 
 Citing ProLIF
 -------------
 
-Please refer to the `citation page <https://prolif.readthedocs.io/en/latest/source/citation.html>`_ on the documentation.
+Please refer to the `citation page <https://prolif.readthedocs.io/en/latest/source/citation.html>`_
+on the documentation.
 
 License
 -------
 
-Unless otherwise noted, all files in this directory and all subdirectories are distributed under the Apache License, Version 2.0 ::
+Unless otherwise noted, all files in this directory and all subdirectories are
+distributed under the Apache License, Version 2.0 ::
 
     Copyright 2017-2023 Cédric BOUYSSET
 
@@ -87,7 +89,7 @@ Unless otherwise noted, all files in this directory and all subdirectories are d
     :target: https://codecov.io/gh/chemosim-lab/ProLIF
 
 .. |docs| image:: https://readthedocs.org/projects/prolif/badge/?version=latest
-    :target: https://prolif.readthedocs.io/en/latest/?badge=latest
+    :target: https://prolif.readthedocs.io/
     :alt: Documentation Status
 
 .. |codeql| image:: https://github.com/chemosim-lab/ProLIF/workflows/CodeQL/badge.svg?branch=master
@@ -98,10 +100,6 @@ Unless otherwise noted, all files in this directory and all subdirectories are d
     :target: http://www.apache.org/licenses/LICENSE-2.0
     :alt: License
 
-.. |binder| image:: https://mybinder.org/badge_logo.svg
-    :target: https://mybinder.org/v2/gh/chemosim-lab/ProLIF/HEAD?filepath=docs%2Fnotebooks
-    :alt: Try it on binder
-
 .. |mdanalysis| image:: 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
     :alt: Powered by MDAnalysis
     :target: https://www.mdanalysis.org

docs/conf.py

@@ -31,7 +31,7 @@
 # -- General configuration ---------------------------------------------------
 
 github_doc_root = "https://github.com/chemosim-lab/ProLIF/tree/master/docs/"
-needs_sphinx = "4.1.2"
+needs_sphinx = "5.3.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -43,17 +43,24 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosectionlabel",
-    "sphinx_rtd_theme",
     "recommonmark",
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
-    "nbsphinx",
+    "myst_nb",
+    "sphinx_copybutton",
 ]
+myst_enable_extensions = [
+    "colon_fence",
+]
+# nb_execution_raise_on_error = True
 
 mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
 autosectionlabel_prefix_document = True
 napoleon_google_docstring = False
 
+# copybutton
+copybutton_exclude = ".linenos, .gp"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -62,15 +69,37 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-source_suffix = [".rst", ".md"]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "myst-nb",
+    ".ipynb": "myst-nb",
+    ".myst": "myst-nb",
+}
 
 # -- 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 = "sphinx_rtd_theme"
+html_theme = "sphinx_book_theme"
 pygments_style = "sphinx"
+html_theme_options = {
+    "repository_url": "https://github.com/chemosim-lab/ProLIF",
+    "path_to_docs": "docs",
+    "use_source_button": True,
+    "use_download_button": True,
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "launch_buttons": {"colab_url": "https://colab.research.google.com"},
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/chemosim-lab/ProLIF",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        }
+    ],
+}
 
 # 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,
@@ -83,7 +112,6 @@
     "https://docs.mdanalysis.org/stable/": None,
     "https://www.rdkit.org/docs/": None,
     "https://pandas.pydata.org/docs/": None,
-    "https://tqdm.github.io/docs/": None,
     "https://multiprocess.readthedocs.io/en/latest/": None,
 }
 

docs/index.rst

@@ -4,22 +4,18 @@ Welcome to ProLIF's documentation!
 .. include:: ../README.rst
 
 .. toctree::
-   :caption: User guide
+   :caption: Information
    :maxdepth: 2
 
    source/installation
    source/citation
    source/changelog
 
 .. toctree::
-   :caption: Tutorials
+   :caption: User Guide
    :maxdepth: 2
-   :numbered:
 
-   notebooks/quickstart
-   notebooks/how-to
-   notebooks/protein-protein_interactions
-   notebooks/visualisation
+   source/tutorials
 
 .. toctree::
    :caption: Documentation