doc updates: upgraded API Proposal to Principles

- principles (we are using the API...)
- edited (took out historical stuff or moved to end)
- minor other doc fixes

CHANGES

@@ -35,6 +35,7 @@ Fixes
 
 Changes
   - defaults for statistical_inefficiency() are more conservative (#39)
+  - API Proposal was upgraded to API Principles (and updated)
 
 (Note: release number 0.2.x was skipped.)
 

docs/api_proposal.rst → docs/api_principles.rst

@@ -1,15 +1,15 @@
-API Proposal
+API principles
 ============
-The following is an API proposal for the library.
-This proposal has been prototyped, with some of the components described already implemented at a basic level.
-This functionality is demoed in [this gist](https://gist.github.com/dotsdl/a41e5756a58e1775e3e3a915f07bfd37).
+
+The following is an overview over the guiding principles and ideas that underpin the API of alchemlyb.
 
 
 `alchemlyb`
 -----------
+
 `alchemlyb` is a library that seeks to make doing alchemical free energy calculations easier and less error prone.
-It will include 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 will be simple in usage and pure in scope, and can be chained together to build customized analyses of data.
+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.
@@ -39,24 +39,33 @@ The library is structured as follows, following a similar style to **scikit-lear
      |   -- openmm
      |  |
      |   -- namd
+     |  |
+     |  |__ ...
      |
       -- preprocessing
      |  |
      |   -- subsampling
+     |  |
+     |  |__ ...
      |
       -- estimators
         |
          -- mbar_
         |
          -- ti_
+        |
+         -- ...
+	 
 
 The ``parsing`` submodule contains parsers for individual MD engines, since the output files needed to perform alchemical free energy calculations vary widely and are not standardized.
-Each module at the very least provides an `extract_u_nk` function for extracting reduced potentials (needed for MBAR), as well as an `extract_DHdl` function for extracting derivatives required for thermodynamic integration.
+Each module at the very least provides an `extract_u_nk` function for extracting reduced potentials (needed for MBAR), as well as an `extract_dHdl` function for extracting derivatives required for thermodynamic integration.
 Other helper functions may be exposed for additional processing, such as generating an XVG file from an EDR file in the case of GROMACS.
-All `extract\_*` functions take similar arguments (a file path, parameters such as temperature), and produce standard outputs (`pandas.DataFrame`s for reduced potentials, `pandas.Series` for derivatives).
+All `extract\_*` functions take similar arguments (a file path,
+parameters such as temperature), and produce standard outputs
+(:class:`pandas.DataFrame` for reduced potentials, :class:`pandas.Series` for derivatives).
 
 The `preprocessing` submodule features functions for subsampling timeseries, as may be desired before feeding them to an estimator.
-So far, these are limited to `slicing`, `statistical_inefficiency`, and `equilibrium_detection` functions, many of which make use of subsampling schemes available from `pymbar`.
+So far, these are limited to `slicing`, `statistical_inefficiency`, and `equilibrium_detection` functions, many of which make use of subsampling schemes available from :mod:`pymbar`.
 These functions are written in such a way that they can be easily composed as parts of complex processing pipelines.
 
 The `estimators` module features classes *a la* **scikit-learn** that can be initialized with parameters that determine their behavior and then "trained" on a `fit` method.
@@ -77,9 +86,16 @@ To enable this, the library will be a community effort.
 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.
-Ian Kenney (@ianmkenney) and Hannes Loeffler (@halx) have also expressed interest in direct development.
-
 Following discussion, refinement, and consensus on this proposal, issues for each need will be posted and work will begin on filling out the rest of the library.
 In particular, parsers will be crowdsourced from the existing community and refined into the consistent form described above.
-Expertise in ensuring theoretical correctness of each component, in particular estimators, will be needed from David Mobley (@davidmobley), John Chodera (@jchodera), and Michael Shirts (@mrshirts).
+
+
+Historical notes
+----------------
+
+Some of the components were originally demoed in `gist a41e5756a58e1775e3e3a915f07bfd37`_.
+
+.. _`gist a41e5756a58e1775e3e3a915f07bfd37`:
+  https://gist.github.com/dotsdl/a41e5756a58e1775e3e3a915f07bfd37
+
+David Dotson (@dotsdl) started the project while employed as a software engineer by Oliver Beckstein (@orbeckst), and this project was a primary point of focus for him in this position.

docs/index.rst

@@ -65,5 +65,5 @@ Contributions are very welcome. If you have bug reports or feature requests or q
    :maxdepth: 1
    :caption: For Developers
 
-   api_proposal
+   api_principles
 

docs/parsing/alchemlyb.parsing.amber.rst

@@ -2,7 +2,9 @@ Amber parsing
 =============
 .. automodule:: alchemlyb.parsing.amber
 
-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.
+The parsers featured in this module are constructed to properly parse `Amber MD`_ output files containing derivatives of the Hamiltonian and FEP (BAR/MBAR) data.
+
+.. _Amber MD: http://ambermd.org/
 
 .. TODO