Update docs (#55)

* doc update (see #53)
  - removed all references to gitter
  - added Contributing section and links to some of our wiki pages
* updates for docs for Amber parsers

README.rst

@@ -1,7 +1,7 @@
 alchemlyb: the simple alchemistry library
 =========================================
 
-|doi| |docs| |build| |cov| |gitter|
+|doi| |docs| |build| |cov|
 
 **Warning**: This library is young. It is **not** API stable. It is a
 nucleation point. By all means use and help improve it, but note that it will
@@ -57,8 +57,3 @@ independent, equilibrated samples [Chodera2016]_.
     :scale: 100%
     :target: https://codecov.io/gh/alchemistry/alchemlyb
 
-.. |gitter| image:: https://badges.gitter.im/alchemistry/alchemlyb.png
-    :alt: Gitter chat
-    :scale: 100%
-    :target: https://gitter.im/alchemistry/alchemlyb
-

docs/api_proposal.rst

@@ -74,7 +74,7 @@ Development model
 
 This is an open-source project, the hope of which is to produce a library with which the community is happy.
 To enable this, the library will be a community effort.
-Development is done in the open on GitHub, with a Gitter channel for discussion among developers for fast turnaround on ideas.
+Development is done in the open on GitHub.
 Software engineering best-practices will be used throughout, including continuous integration testing via Travis CI, up-to-date documentation, and regular releases.
 
 David Dotson (@dotsdl) is employed as a software engineer by Oliver Beckstein (@orbeckst), and this project is a primary point of focus for him in this position.

docs/index.rst

@@ -6,16 +6,17 @@
 alchemlyb: the simple alchemistry library
 =========================================
 
-.. warning:: This library is in an **alpha** state. The library and the documentation is incomplete. Use in production at your own risk.
-
-**alchemlyb** is a library for doing alchemical free energy calculations more easily and with less prone for error.
+**alchemlyb** is a library for doing alchemical free energy calculations more easily.
 It includes functions for parsing data from formats common to existing MD engines, subsampling these data, and fitting these data with an estimator to obtain free energies.
 These functions are simple in usage and pure in scope, and can be chained together to build customized analyses of data.
 
 **alchemlyb** seeks to be as boring and simple as possible to enable more complex work.
 Its components allow work at all scales, from use on small systems using a single workstation to larger datasets that require distributed computing using libraries such as `dask`_.
 
+The library is *under active development* and the API is still somewhat in flux. However, it is used by multiple groups in a production environment. We use `semantic versioning`_ to indicate clearly what kind of changes you may expect between releases. See :ref:`contact` for how to get in touch if you have questions or find problems.
+
 .. _`dask`: http://dask.pydata.org
+.. _`semantic versioning`: https://semver.org
 
 Core philosophy
 ---------------
@@ -25,16 +26,31 @@ With its goal to remain simple to use, **alchemlyb**'s design philosophy follows
 2. For estimators, mimic the **scikit-learn** API as much as possible.
 3. Aim for a consistent interface throughout, e.g. all parsers take similar inputs and yield a common set of outputs.
 
+For more details, see the Roadmap_.
+
+.. _Roadmap: https://github.com/alchemistry/alchemlyb/wiki/Roadmap
+
+
 Development model
 -----------------
 This is an open-source project, the hope of which is to produce a library with which the community is happy.
 To enable this, the library is a community effort.
-Development is done in the open on `GitHub`_, with a `Gitter`_ channel for discussion among developers for fast turnaround on ideas.
+Development is done in the open on `GitHub`_.
+
+Software engineering best-practices are used throughout, including continuous integration testing via Travis CI, up-to-date documentation, and regular releases.
 
 .. _`GitHub`: https://github.com/alchemistry/alchemlyb
-.. _`Gitter`: https://gitter.im/alchemistry/alchemlyb
 
-Software engineering best-practices are used throughout, including continuous integration testing via Travis CI, up-to-date documentation, and regular releases.
+
+.. _contact:
+
+Contributing
+------------
+Contributions are very welcome. If you have bug reports or feature requests or questions then please get in touch with us through the `Issue Tracker`_. We also welcome code contributions: have a look at our `Developer Guide`_ and submit a pull request against the `alchemistry/alchemlyb`_ GitHub repository.
+
+.. _`Developer Guide`: https://github.com/alchemistry/alchemlyb/wiki/Developer-Guide
+.. _`Issue Tracker`: https://github.com/alchemistry/alchemlyb/issues
+.. _`alchemistry/alchemlyb`: https://github.com/alchemistry/alchemlyb
 
 .. toctree::
     :maxdepth: 1

docs/parsing/alchemlyb.parsing.amber.rst

@@ -2,15 +2,13 @@ Amber parsing
 =============
 .. automodule:: alchemlyb.parsing.amber
 
-The parsers featured in this module are constructed to properly parse Amber_ output files containing derivatives of the Hamiltonian. At the moment, only derivatives are available for TI-based estimators.
+The parsers featured in this module are constructed to properly parse `Amber <http://ambermd.org/>`_ output files containing derivatives of the Hamiltonian and FEP (BAR/MBAR) data.
 
 .. TODO
    
    Notes on what options need to be set in Amber to produce the required output.  See the Gromacs parser page for an example of the information that we would like to have here.
 
 
-.. _`Amber`: http://ambermd.org/
-
 
 API Reference
 -------------

src/alchemlyb/parsing/amber.py

@@ -1,4 +1,5 @@
-"""Parsers for extracting alchemical data from Amber_ output files.
+"""Parsers for extracting alchemical data from `Amber <http://ambermd.org>`_ output files.
+
 Most of the file parsing parts are inherited from
 `alchemical-analysis`_.
 
@@ -248,6 +249,20 @@ def file_validation(outfile):
 
 
 def extract_u_nk(outfile):
+    """Return reduced potentials `u_nk` from Amber outputfile.
+
+    Parameters
+    ----------
+    outfile : str
+        Path to Amber .out file to extract data from.
+
+    Returns
+    -------
+    u_nk : DataFrame
+        Potential energy for each alchemical state (k) for each frame (n).
+
+    """
+
     file_datum = file_validation(outfile)
     if not file_validation(outfile):   # pragma: no cover
         return None