Add application example to example.ipynb (#12)

* Added application example to example.ipynb

* Add __str__, __repr__, fix some .md

* Try add Binder

* [ci skip] Fix binder link

* Stylize docs

* [ci skip] Skip trailing WS in .bump2version

* [ci skip] D-orthogonal warning verbosity, mu=100

* Add extra Copyright note in _util.py docstrings.

* Update example.ipynb with toy matrix provided by Marius.

* Change dtype to np.complex64

* Fix sphinx warnings

* Do not fail RTD on warnings

* [ci skip] Add spellcheck, fix typos

* [ci skip] Fix css, update classifier and doc

* Specify credits to MSMTools.

* Add key contributors to RTD.

Co-authored-by: michalk8 <michal.klein@protonmail.com>

Author: msmdev

.bumpversion.cfg

@@ -4,5 +4,4 @@ commit = True
 tag = True
 files = setup.py pygpcca/__init__.py
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)
-serialize =
-	{major}.{minor}.{patch}
+serialize = {major}.{minor}.{patch}

.pre-commit-config.yaml

@@ -48,6 +48,7 @@ repos:
     -   id: mixed-line-ending
         args: [--fix=lf]
     -   id: trailing-whitespace
+        exclude: ^.bumpversion.cfg$  # trailing whitespace
     -   id: name-tests-test
         args: [--django]
     -   id: check-case-conflict

.readthedocs.yml

@@ -3,7 +3,7 @@ version: 2
 sphinx:
     builder: html
     configuration: docs/source/conf.py
-    fail_on_warning: true
+    fail_on_warning: false
 
 formats:
 -   htmlzip

README.rst

@@ -5,13 +5,13 @@ pyGPCCA - Generalized Perron Cluster Cluster Analysis
 Generalized Perron Cluster Cluster Analysis program to coarse-grain reversible and non-reversible Markov State Models.
 
 Markov State Models (MSM) enable the identification and analysis of metastable states and related kinetics in a
-very instructive manner. They are widely used, e.g. to model molecular or cellular kinetics.
+very instructive manner. They are widely used, e.g. to model molecular or cellular kinetics. |br|
 Common state-of-the-art Markov state modeling methods and tools are very well suited to model reversible processes in
 closed equilibrium systems. However, most are not well suited to deal with non-reversible or even non-autonomous
-processes of non-equilibrium systems.
+processes of non-equilibrium systems. |br|
 To overcome this limitation, the Generalized Robust Perron Cluster Cluster Analysis (G-PCCA) was developed.
 The G-PCCA method implemented in the *pyGPCCA* program readily handles equilibrium as well as non-equilibrium data by
-utilizing real Schur vectors instead of eigenvectors.
+utilizing real Schur vectors instead of eigenvectors. |br|
 *pyGPCCA* enables the semiautomatic coarse-graining of transition matrices representing the dynamics of the system
 under study. Utilizing *pyGPCCA*, metastable states as well as cyclic kinetics can be identified and modeled.
 
@@ -43,7 +43,7 @@ Example
 Please refer to our `example usage <https://pygpcca.readthedocs.io/en/latest/example.html>`_ in the documentation.
 
 .. |PyPI| image:: https://img.shields.io/pypi/v/pygpcca
-    :target: https://pypi.org/project/pygpcca
+    :target: https://pypi.org/project/pygpcca/
     :alt: PyPI
 
 .. |Conda| image:: https://img.shields.io/conda/vn/conda-forge/pygpcca
@@ -68,3 +68,7 @@ Please refer to our `example usage <https://pygpcca.readthedocs.io/en/latest/exa
 
 .. _`PETSc`: https://www.mcs.anl.gov/petsc/
 .. _`SLEPc`: https://slepc.upv.es/
+
+.. |br| raw:: html
+
+  <br/>

docs/requirements.txt

@@ -3,5 +3,7 @@ nbsphinx>=0.7
 sphinx>=3.3.0
 sphinx-autodoc-annotation
 sphinx-autodoc-typehints>=1.10.3
+sphinx-copybutton
 sphinx_last_updated_by_git
 sphinx_rtd_theme
+sphinxcontrib-spelling

docs/source/_key_contributors.rst

@@ -0,0 +1,11 @@
+.. sidebar:: Key Contributors
+   :subtitle: `pyGPCCA graph`_ | ☀ = maintainer
+
+   * `Bernhard Reuter`_: lead developer ☀
+   * `Michal Klein`_: developer, diverse contributions
+   * `Marius Lange`_: developer, diverse contributions
+
+.. _pyGPCCA graph: https://github.com/msmdev/pyGPCCA/graphs/contributors
+.. _Bernhard Reuter: https://github.com/msmdev
+.. _Michal Klein: https://github.com/michalk8
+.. _Marius Lange: https://github.com/Marius1311

docs/source/_static/.gitkeep

@@ -0,0 +1,26 @@
+.wy-nav-content {
+    max-width: 1000px;
+}
+
+.wy-side-nav-search {
+    background-color: #2961b9;
+}
+
+.wy-side-nav-search input[type="text"] {
+    border-radius: 6px!important;
+}
+
+.highlight {
+    background: #f6f5f9;
+}
+
+html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) > dt {
+    color: #404040;
+    background-color: #90b2ff45;
+    border-top: solid 4px #2932b9c4;
+}
+
+.rst-content code.literal {
+    color: #404040;
+    font-weight: 700;
+}

docs/source/_static/css/custom.css

@@ -0,0 +1,3 @@
+# TODO: once this is on PyPI, use PyPI version
+git+https://github.com/msmdev/pyGPCCA
+matplotlib

docs/source/binder/requirements.txt

@@ -4,14 +4,15 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-from typing import List
 from pathlib import Path
 from datetime import datetime
 import os
 
 # -- Path setup --------------------------------------------------------------
 import sys
 
+from sphinx.application import Sphinx
+
 HERE = Path(__file__).parent
 sys.path.insert(0, str(HERE.parent.parent))
 sys.path.insert(0, os.path.abspath("_ext"))
@@ -21,13 +22,14 @@
 needs_sphinx = "3.3"
 # -- Project information -----------------------------------------------------
 
-project = "pygpcca"
+project = "pyGPCCA"
 author = pygpcca.__author__
 copyright = f"{datetime.now():%Y}, {author}"  # noqa: A001
 
 # The full version, including alpha/beta/rc tags
 master_doc = "index"
-release = "0.0.0"
+release = "main"
+version = f"main ({pygpcca.__version__})"
 
 
 # -- General configuration ---------------------------------------------------
@@ -44,6 +46,7 @@
     "sphinx.ext.mathjax",
     "sphinx_autodoc_typehints",
     "sphinx_last_updated_by_git",
+    "sphinx_copybutton",
     "typed_returns",
     "nbsphinx",
 ]
@@ -59,7 +62,7 @@
 # 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: List[str] = []
+exclude_patterns = ["build", "**.ipynb_checkpoints"]
 
 source_suffix = ".rst"
 add_function_parentheses = True
@@ -84,6 +87,32 @@
 napoleon_use_admonition_for_references = False
 todo_include_todos = False
 
+# binder
+nbsphinx_highlight_language = "python3"
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'png', 'pdf'}",  # correct figure resize
+    "--InlineBackend.rc={'figure.dpi': 96}",
+]
+nbsphinx_prolog = r"""
+{% set docname = 'docs/source/' + env.doc2path(env.docname, base=None) %}
+.. raw:: html
+
+    <div class="note">
+      Interactive version
+      <a href="https://mybinder.org/v2/gh/msmdev/pygpcca/{{ env.config.release|e }}?filepath={{ docname|e }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom">
+      </a>
+    </div>
+"""  # noqa: E501
+
+# spelling
+spelling_lang = "en_US"
+spelling_warning = True
+spelling_word_list_filename = "spelling_wordlist.txt"
+spelling_add_pypi_package_names = True
+spelling_show_suggestions = True
+# see: https://pyenchant.github.io/pyenchant/api/enchant.tokenize.html
+spelling_filters = ["enchant.tokenize.URLFilter", "enchant.tokenize.EmailFilter"]
+
 # 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".
@@ -93,3 +122,7 @@
 html_show_sphinx = False
 html_use_smartypants = True
 pygments_style = "sphinx"
+
+
+def setup(app: Sphinx) -> None:
+    app.add_css_file("css/custom.css")