License and doc updates

- License must be GPL (cannot be LGPL because MDAnalysis is linked and it is GPL) - updated installation docs - cleaned up docs: top level page now has more useful info - cleaned up repo README and INSTALL
Becksteinlab · Sep 5, 2018 · 1620867 · 1620867
1 parent 13316bf
commit 1620867
Show file tree

Hide file tree

Showing 7 changed files with 139 additions and 608 deletions.
diff --git a/COPYING.LESSER b/COPYING.LESSER
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -9,159 +9,49 @@ should be installed before Hop and Hop's installation process. The
 latter should be painless because it only consists of pure python
 scripts at the moment.
 
+.. warning:: 
+
+   This is legacy research code. It might not work at all. Use at your
+   own risk. Feedback is very welcome through the `issue tracker`_.
 
-Quick instructions
-==================
 
-If you are familiar with `pip`_ then try ::
+.. _issue tracker: https://github.com/becksteinlab/hop/issues
 
-  pip install Hop-0.3.3.tar.gz
+.. Note:: Only Python 2.7 is currently supported.
 
-or ::
 
-  cd Hop-0.3.3
-  python setup.py install
-
-Otherwise read the `Requirements`_ and `Installation`_ instructions below.
-
-.. _pip: http://www.pip-installer.org/en/latest/
-
-
-Requirements
-============
-
-If Hop is installed with `pip`_ then some dependencies are handled
-automatically; if not you will have to install packages manually. This
-is always true for ``MDAnalysis`` at the moment.
-
-The ``GridDataFormats`` package can be obtained from my home page (see
-below) but in most cases the installation should be able to
-automatically download and install it.
-
-Installing :mod:`matplotlib` (if plotting is desired) tends to be less
-painful if it is done in advance, especially through your system's
-package manager.
-
-
-System requirements
+.. _source-install:
+
+Source installation
 -------------------
 
-Tested with python 2.5, 2.6 (2.3 will not work anymore) on Linux and Mac OS X.
-
-
-Required python packages
-------------------------
-
-.. Table:: Required packages for Hop.
-
-   =============== ===================== ============================================================
-   package         version               url
-   =============== ===================== ============================================================
-   MDAnalysis      >= 0.7.5              http://www.mdanalysis.org
-   numpy           >=1.0.3               http://numpy.scipy.org
-   NetworkX        >=1.0                 https://networkx.lanl.gov
-   GridDataFormats >= 0.1.1              https://github.com/MDAnalysis/GridDataFormats
-   =============== ===================== ============================================================
-
-MDAnalysis_ requires additional modules; see the instructions at
-its home page. Get the latest snapshot from
-http://downloads.mdanalysis.org or install it with ::
-
-  pip install MDAnalysis
-
-Note that installation of MDAnalysis_ can take a while because it
-requires a python environment that is fully set up for scientific
-computing. The good news is that once this is done then Hop should be
-easy.
-
-.. _MDAnalysis:: http://www.mdanalysis.org
-
-
-Optional packages
------------------
-
-The following packages should be installed to make best use of
-Hop, especially for visualization.
-
-.. Table:: Optional packages for Hop.
-
-   =============== ===================== ============================================================
-   package         version               url
-   =============== ===================== ============================================================
-   pygraphviz                            https://networkx.lanl.gov/pygraphviz/
-   matplotlib       >=0.91.3             http://matplotlib.sourceforge.net/ 
-   rpy (and R)                           http://rpy.sourceforge.net/
-   biopython                             http://www.biopython.org
-   =============== ===================== ============================================================
-
-When these modules are missing the code will raise an :exc:`ImportError` when
-attempting to use them; their absence is not always handled gracefuly
-and it is suggested to install at least :mod:`matplotlib` (pylab). 
-
-:program:`R` and :mod:`rpy` are only used for an experimental heatmap analysis
-and can be safely ignored.
-
-:mod:`pygraphviz` also requires :program:`graphviz`; see its own installation
-instructions.
-
-
-
-Optional external helper programs
----------------------------------
-
-Some functions and classes can make use of external programs; none of
-them are necessary for the core functionality of Hop but are listed
-here for completeness.
-
-VMD
-     VMD's VolMap plugin can be used to generate densities. See
-     `Visualization`_ for details on VMD.
-
-
-
-
-Hints on obtaining packages
----------------------------
-
-Many packages can be found through the local package manager (eg apt,
-fink, yum, rpm). ``networkx`` is available at the above URL or with
-the ``pip`` command.
-
-In Debian/Ubuntu::
-
-   aptitude install python-setuptools pkg-config
-
-   aptitude install graphviz graphviz-dev python-matplotlib
-   pip install networkx
-   pip install pygraphviz
+At the moment, only source installation is supported. Use pip_. Download the
+tarball from https://github.com/Becksteinlab/hop/releases or do a
+web-install:
 
+.. code-block:: bash
 
+   		pip install https://github.com/Becksteinlab/hop/archive/release-0.4.0.tar.gz
 
-Additional software
-===================
+(This will also install all dependencies.)
 
-The following software is not necessary to use the package itself but
-has been found extremely useful by the author for using Hop or
-analyzing data.
+.. _pip: https://pip.pypa.io
 
 
-Interactive use and ``ipython``
--------------------------------
+Conda
+-----
 
-When Hop was developed, interactive use from a python command shell
-turned out to be a very convenient application paradigm. ``ipython``
-is very much recommended because of its ease to obtain interactive
-help via ``?`` and ``??`` and to inspect objects via
-TAB-completion. This is especially helpful because most of the
-documentation is provided as python doc strings, both at the module
-and at the class level.
+At the moment, we do not have a conda package. However, it is easy to
+set up a working environment for *hop* and the do the :ref:`install from
+source <source-install>`_ described above.
 
-For instance, to get an overview over interactive usage, load the
-hop.interactive module and query the top level doc string::
+.. code-block:: bash
 
- import hop.interactive
- hop.interactive ?
+		conda create -c conda-forge -n hop python=2.7 numpy scipy networkx MDAnalysis matplotlib pygraphviz GridDataFormats
+		source activate hop
 
+		pip install https://github.com/Becksteinlab/hop/archive/release-0.4.0.tar.gz
+
 
 Visualization
 -------------

diff --git a/README.rst b/README.rst
@@ -2,7 +2,7 @@
  README
 ========
 
-|zenodo|
+|docs| |zenodo|
 
 **DEVELOPMENT VERSION of hop**: Please note that this is a beta
 version of the package. It is still in heavy development. Feedback_ is
@@ -48,8 +48,12 @@ installed beforehand.
 Documentation
 =============
 
-Please see the contents of the ``doc/`` directory, in particular
-``doc/overview.txt``, and the Python doc strings.
+Please see the `online docs`_.
+
+There is also some contents in the ``doc/`` directory, in particular
+``doc/overview.txt``.
+
+.. _online docs: https://hop.readthedocs.io
 
 
 Bug reporting and Contributing
@@ -78,6 +82,10 @@ MDAnalysis):
 
 Thanks!
 
+.. |docs| image:: https://readthedocs.org/projects/hop/badge/?version=latest
+   :target: https://hop.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation
+
 .. |zenodo| image:: https://zenodo.org/badge/13219/Becksteinlab/hop.svg
    :target: https://zenodo.org/badge/latestdoi/13219/Becksteinlab/hop
    :alt: Zenodo DOI