Merge pull request #39 from markovmodel/docsfixes

All tests are passing. CI failures have to do with coverage reports

.coveragerc

@@ -1,2 +1,3 @@
 [run]
 branch = true
+

devtools/conda-recipe/meta.yaml

@@ -26,16 +26,23 @@ requirements:
 test:
   source_files:
     - .coveragerc
+    - molpx/notebooks/*
   requires:
     - pip
-    - pytest
-    - pytest-cov
+    - pytest ==3.2.5
+    - pytest-cov ==2.5.1
+    - coverage ==4.4.2
+#    - nbval ==0.7
   imports:
     - molpx
   commands:
-    - pip install git+https://github.com/computationalmodelling/nbval
+    - pip install git+https://github.com/computationalmodelling/nbval@0.9
     - pytest -vv --pyargs molpx --cov=molpx --cov-report=xml --current-env --nbval-lax
-    - python -c "import shutil, os; shutil.copy('coverage.xml', os.path.expanduser('~'))"
+    #- pytest -vv --pyargs molpx --cov=molpx --current-env --cov-report=xml
+    #- ls -R
+    #- pwd
+    #- pytest -vv --current-env --nbval-lax
+    - python -c "import shutil, os; shutil.copy('coverage.xml', os.path.expanduser('~'))" || true
 about:
   home: https://github.com/gph82/projection_explorer
   license: GNU Lesser Public License v3+

doc/source/INSTALL.rst

@@ -7,7 +7,7 @@ available in their required versions, the installation will fail. We recommend o
 that is relatively safe, but you are welcome to try another approaches if you know what you are doing.
 
 
-Anaconda install (Recommended)
+Anaconda Install (recommended)
 ==============================
 
 We strongly recommend to use the Anaconda scientific python distribution in order to install
@@ -18,8 +18,7 @@ but play at your own risk.
 
 If you already have a conda installation, directly go to step 3:
 
-1. Download and install miniconda for Python 2.7 or 3+, 32 or 64 bit depending on your system. Note that
-   you can still use Python 2.7, however we recommend to use Python3:
+1. Download and install miniconda for Python 3+, 32 or 64 bit depending on your system.
 
    http://conda.pydata.org/miniconda.html
 
@@ -35,27 +34,33 @@ If you already have a conda installation, directly go to step 3:
 2. If you have installed from a Linux shell, either open a new shell to have an updated PATH,
    or update your PATH variable by ``source ~/.bashrc`` (or .tcsh, .csh - whichever shell you are using).
 
-3. Add the omnia-md software channel, and install (or update) molPX:
+3. Install molPX using the conda-forge channel:
 
-   .. code::
+   ::
 
-      conda config --add channels omnia
-      conda install pyemma
+      conda install molpx -c conda-forge
 
-   if the command conda is unknown, the PATH variable is probably not set correctly (see 1. and 2.)
+   if the command ``conda`` is unknown, the PATH variable is probably not set correctly (see 1. and 2.)
 
 4. Check installation:
 
-   .. code::
+   ::
 
       conda list
 
-   shows you the installed python packages. You should find a molpx 0.1.2 (or later)
-   and ipython, ipython-notebook 3.1 (or later). If ipython is not up to date, you canot use molPX. Please update it by
+   shows you the installed python packages. You should find a molpx 0.1.2 (or later).
+   molPX requires all the following packages, s. t. they will be installed (and their dependencies) if they
+   are not installed already.
 
-   .. code::
+   ::
 
-      conda install ipython-notebook
+      nglview>=1
+      ipywidgets>=7
+      pyemma
+      scikit-learn
+      notebook
+      mdtraj
+      ipympl
 
 Python Package Index (PyPI)
 ===========================
@@ -116,7 +121,23 @@ but be aware that success is not guaranteed. See the "Known Issues" below.
 
 Known Issues
 =============
- * A ``SandboxViolation`` error might appear when installing from source. Until we figure this out,
+ * After a successfull installation and execution of ``molpx.example_notebooks()``...no widgets are shown! Most probably, this has to do with `nglview <https://github.com/arose/nglview/#released-version>`_ and its needed Jupyter notebook extensions.
+ **This is a known, frustrating behaviour:**
+
+    * `deja vu: nglview widget does not appear <https://github.com/arose/nglview/issues/599>`_
+    * `nglview widget does not appear <https://github.com/arose/nglview/issues/718>`_
+    * `Troubleshooting: nglviewer fresh install tips <https://github.com/SBRG/ssbio/wiki/Troubleshooting#nglviewer-fresh-install-tips>`_
+
+  We'are aware of this and molPX automatically checks for the needed extensions every time it gets imported, s.t. it will refuse
+  to start-up if it finds any problems. If somehow it manages to start-up but no widget is shown, try issuing
+    ::
+
+        molpx._auto_enable_extensions()
+
+    restarting everything and trying again. Otherwise, check the above links.
+
+ * A ``SandboxViolation`` error might appear when installing from source. This is because the ``nglview`` dependency
+ is trying to enable the needed extensions. Until we figure this out,
  try to install ``nglview`` externally issuing:
 
 
@@ -127,5 +148,3 @@ Known Issues
     >>> pip install nglview
 
  * Note that molPX only works with ``nglview`` versions >=0.6.2.1.
-
- * The interplay between some modules (nglview, nbextensions, ipywidgets) might limit you to use python3.X on some platforms. Sorry about that.

doc/source/conf.py

@@ -380,8 +380,9 @@ def __getattribute__(self, item):
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'https://docs.python.org/': None, 
 intersphinx_mapping = {'pyemma': ('http://www.emma-project.org/latest/', None),
+                       'matplotlib': ('http://matplotlib.org/', None),
                        'mdtraj': ('http://mdtraj.org/latest/', None),
-                       'pylab' : ('http://matplotlib.org/api/', None),
+                       #'pylab' : ('http://matplotlib.org/api/', None),
                        'nglview' : ('http://arose.github.io/nglview/latest/', None)
 }
 

doc/source/index_visualize.rst

@@ -10,10 +10,10 @@ The core functionality is to link two interative figures, *fig1* and *fig2*, ins
 so that an action in *fig1* (e.g.a click of the mouse or a slide of a slidebar) will trigger an event in *fig2*
 (e.g. a frame update or point moved) and vice versa. Usually, these two figures contain representations from:
 
-* **molecules**:  an `nglviewer <https://github.com/arose/nglview>`_ widget showing one (or more) molecular structure(s) that a particular value of the coordinate(s) is associated with and
+* **molecules**:  an `NGLview <https://github.com/arose/nglview>`_ widget showing one (or more) molecular structure(s) that a particular value of the coordinate(s) is associated with and
 * **projected coordinates**: a matplotlib figure showing the projected coordinates (e.g. TICs or PCs or any other), :math:`{Y_0, ..., Y_N}`, either as a 2D histogram, :math:`PDF(Y_i, Y_j)` or as trajectory views :math:`{Y_0(t), ...Y_N(t)}`
 
-You are **strongly encouraged** to check nglview's `documentation <https://github.com/arose/nglview>`_, since its functionalities extend beyond the scope of this package and the molecular visualization universe is rich and complex (unlike this module).
+You are **strongly encouraged** to check NGLview's `documentation <https://github.com/arose/nglview>`_, since its functionalities extend beyond the scope of this package and the molecular visualization universe is rich and complex (unlike this module).
 
 The methods offered by this module are:
 

molpx/__init__.py

@@ -132,6 +132,11 @@ def _get_extension_status(ext_list=_ext_mapping.keys()):
 
     return enabled_exts
 
+def _auto_enable_extensions():
+    r"""Try to automatically enable the needed extensions. Won't throw exception on failuer"""
+    for _ext, _path in _ext_mapping.items():
+        _enable_extensions(_ext_mapping[_ext])
+
 def _enable_extensions(this_ext_path):
     r""" Try to install/enable an extension.
     Prompt the user to do so if an exception is thrown
@@ -155,8 +160,10 @@ def _enable_extensions(this_ext_path):
 
 # Try to help the user getting molpx working out of the box and raise an Exception if molpx wont work
 if not all(_get_extension_status().values()):
-    for ext, enabled in _get_extension_status().items():
-        if not enabled:
-            if not _enable_extensions(_ext_mapping[ext]):
+    for _ext, _enabled in _get_extension_status().items():
+        if not _enabled:
+            if not _enable_extensions(_ext_mapping[_ext]):
                 raise ModuleNotFoundError("Could not initialize molpx")
 
+
+

molpx/_bmutils.py

@@ -1,4 +1,3 @@
-from __future__ import print_function
 import numpy as _np
 import mdtraj as _md
 

molpx/_linkutils.py

@@ -1,4 +1,3 @@
-from __future__ import print_function
 import numpy as _np
 
 from matplotlib.widgets import AxesWidget as _AxesWidget

molpx/_nbtools.py

@@ -1,5 +1,3 @@
-from __future__ import print_function
-
 import warnings as _warnings
 import os as _os
 import sys as _sys

molpx/generate.py

@@ -1,4 +1,3 @@
-from __future__ import print_function
 
 __author__ = 'gph82'