Merge pull request #21 from markovmodel/docsfixes

Added installation guide copied from PyEMMA

README.rst

@@ -29,19 +29,16 @@ Find more about the people behind molPX here:
 Download and Install
 =====================
 
-At the moment, the easiest way is to get molPX is from `PyPI - the Python Package Index
-<https://pypi.python.org/pypi/molPX/>`_ using `pip <https://packaging.python.org/installing/>`_ by typing this command
-from the terminal:
+If you can't wait to play around with molPX, and you have the `Anaconda scientifc python distribution
+<https://www.continuum.io/downloads>`_ (which we strongly recommend), the easiest way to get molPX is to issue
+the `conda command <https://conda.io/docs/intro.html>`_:
 
-    >>> pip install molpx
+   >>> conda install molPX -c omnia
 
-You can also clone or download the `source from github <https://github.com/markovmodel/molPX>`_.
-After that, just cd to the download directory (and untar/unzip if necessary) and:
+and jump to the Quick Start section of this document. Otherwise, check out our more exhaustive
 
-    >>> cd molPX
-    >>> python setup.py install
+* :doc:`Installation Guide </INSTALL>`
 
-See the "Known Issues" below if you get a ``SandboxViolation`` error.
 
 Quick Start
 =============
@@ -55,23 +52,40 @@ Import ``molpx`` and let the example notebook guide you
     >>> import molpx
     >>> molpx.example_notebook()
 
-These commands should put you in front of a jupyter notebook explaining the basic functionality of molPX
+Voilà: you should be looking at a jupyter notebook explaining the basic functionality of molPX
 
 Documentation
 ==============
 
 You can find the latest documentation online `here <https://molpx.readthedocs.io/>`_
-You can build a local copy of the html documentation by issuing
+You can build a local copy of the html documentation by navigating to the molPX installation
+directory and issuing:
 
     >>> cd doc
     >>> make html
 
-This will generate `molPX/docs/build/html/index.html` with the html documentation.
+This will generate `molPX/docs/build/html/index.html` with the html documentation. If you are missing some of
+the requirements for the documentation , issue:
+
+    >>> pip install -r ./source/doc_requirements.txt
+
+If you don't know where molPX is installed, you can find out this way:
+
+    >>> ipython
+    >>> import molpx
+    >>> molpx._molpxdir()
+
+The output of the last command is one subdirectory of molPX's installation directory, so just copy it and issue:
+
+    >>> cd the-output-of-the-molpx._molpxdir-command
+    >>> cd ..
+
+and you are there !
 
 Warnings
 =========
 
- * molPX is currently under heavy development and the API might change rapidly.
+molPX is currently under heavy development and the API might change rapidly. Stay tuned.
 
 Data Privacy Statement
 ======================
@@ -86,6 +100,7 @@ When you import this Python package, some of your metadata is sent to our server
 
 How to disable this feature easily:
 -----------------------------------
+
 Even before you use molPX for the first time:
 
  1. Create a hidden folder `.molpx` in your home folder

doc/source/INSTALL.rst

@@ -0,0 +1,131 @@
+============
+Installation
+============
+
+To install molPX , you need a few Python package dependencies. If these dependencies are not
+available in their required versions, the installation will fail. We recommend one particular way for the installation
+that is relatively safe, but you are welcome to try another approaches if you know what you are doing.
+
+
+Anaconda install (Recommended)
+==============================
+
+We strongly recommend to use the Anaconda scientific python distribution in order to install
+python-based software. Python-based software is not trivial to distribute
+and this approach saves you many headaches and problems that frequently arise in other installation
+methods. You are free to use a different approach (see below) if you know how to sort out problems,
+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:
+
+   http://conda.pydata.org/miniconda.html
+
+
+   For Windows users, who do not know what to choose for 32 or 64 bit, it is strongly
+   recommended to read the second question of this FAQ first:
+
+   http://windows.microsoft.com/en-us/windows/32-bit-and-64-bit-windows
+
+
+   Run the installer and select **yes** to add conda to the **PATH** variable.
+
+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:
+
+   .. code::
+
+      conda config --add channels omnia
+      conda install pyemma
+
+   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
+
+   .. code::
+
+      conda install ipython-notebook
+
+Python Package Index (PyPI)
+===========================
+
+If you do not like Anaconda for some reason you should use the Python package
+manager **pip** to install. This is not recommended, because in the past,
+various problems have arisen with pip in compiling the packages that molPX depends upon, see `this issue
+<https://github.com/markovmodel/molPX/issues/16>`_ for more information.
+
+1. If you do not have pip, please read the install guide:
+   `install guide <http://pip.readthedocs.org/en/latest/installing.html>`_.
+
+2. Make sure pip is enabled to install so called
+   `wheel <http://wheel.readthedocs.org/en/latest/>`_ packages:
+
+   ::
+
+      pip install wheel
+
+   Now you are able to install binaries if you use MacOSX or Windows.
+
+3. Install molPX using
+
+   ::
+
+      pip install molPX
+
+4. Check your installation
+
+   ::
+
+      python
+      >>> import molpx
+      >>> molpx.__version__
+
+   should print 0.1.2 or later
+
+   ::
+
+      >>> import IPython
+      >>> IPython.__version__
+
+   should print 3.1 or later. If ipython is not up to date, update it by ``pip install ipython``
+
+Building from Source
+====================
+Building all dependencies from molPX from source is sometimes (if not usually) tricky, takes a
+long time and is error prone. **It is not recommended nor supported by us.**
+If unsure, use the Anaconda installation.
+
+What you can do is clone or download the `source from github <https://github.com/markovmodel/molPX>`_.
+After that, just cd to the download directory (and untar/unzip if necessary) and:
+
+    >>> cd molPX
+    >>> python setup.py install
+
+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,
+ try to install ``nglview`` externally issuing:
+
+
+    >>> conda install nglview -c bioconda
+
+    or, alternatively
+
+    >>> 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

@@ -31,6 +31,7 @@ def __getattribute__(self, item):
         return MagicMock()
 
 MOCK_MODULES = ['mdtraj',
+                'pyemma.coordinates.transform',
                 'pyemma.coordinates',
                 'pyemma.plots',
                 'pyemma.util.linalg',

doc/source/index.rst

@@ -12,6 +12,7 @@
    molpx.generate  <index_generate>
    Example Jupyter Notebook <index_notebooks>
    About & YouTube Introduction <about>
+   Installation Guide <INSTALL>
 
 Indices and tables
 ==================