updated docs significantly, adding features and better intro example

CHANGELOG.rst

@@ -15,6 +15,9 @@ come in v2.1.0, which may again be backward incompatible. Though this is not ide
 backwards-incompatible changes will be restricted to increase in the major version number),
 this has been driven by time constraints.
 
+Known issues with this version, to be addressed by the next, are that both scripts (hmf and hmf-fit)
+are buggy and untested. Don't use these until the next version unless you're crazy.
+
 Features
 ++++++++
 - New methods on all frameworks to list all parameters, defaults and current values.

README.rst

@@ -2,7 +2,7 @@
 hmf
 ===
 
-**The halo mass function calculator**
+**The halo mass function calculator.**
 
 .. image:: https://travis-ci.org/steven-murray/hmf.png?branch=master   
 		:target: https://travis-ci.org/steven-murray/hmf
@@ -14,10 +14,8 @@ hmf
         :target: https://coveralls.io/github/steven-murray/hmf?branch=master
 
 `hmf` is a python application that provides a flexible and simple way to calculate the 
-Halo Mass Function for any input cosmology, redshift, dark matter model, virial
-overdensity or several other variables. Addition of further variables should be simple. 
-
-It is also the backend to `HMFcalc <http://hmf.icrar.org>`_, the online HMF calculator.
+Halo Mass Function for a range of varying parameters. It is also the backend to
+`HMFcalc <http://hmf.icrar.org>`_, the online HMF calculator.
 
 Documentation
 -------------

docs/index.rst

@@ -5,6 +5,28 @@
 
 .. include:: ../README.rst
 
+Features
+--------
+* Calculate mass functions and related quantities extremely easily.
+* Very simple to start using, but wide-ranging flexibility.
+* Caching system for optimal parameter updates, for efficient iteration over parameter space.
+* Support for all LambdaCDM cosmologies.
+* Focus on flexibility in models. Each "Component", such as fitting functions, filter functions,
+  growth factor models and transfer function fits are implemented as generic classes that
+  can easily be altered by the user without touching the source code.
+* Focus on simplicity in frameworks. Each "Framework" mixes available "Components" to derive
+  useful quantities -- all given as attributes of the Framework.
+* Comprehensive in terms of output quantities: access differential and cumulative mass functions,
+  mass variance, effective spectral index, growth rate, cosmographic functions and more.
+* Comprehensive in terms of implemented Component models
+    * 5+ models of transfer functions including directly from CAMB
+    * 4 filter functions
+    * 20 hmf fitting functions
+* Includes models for Warm Dark Matter
+* Nonlinear power spectra via HALOFIT
+* Functions for sampling the mass function.
+* CLI scripts both for producing any quantity included, or fitting any quantity.
+
 Installation
 ------------
 `hmf` is built on several other packages, most of which will be familiar to the
@@ -13,7 +35,9 @@ installed when installing `hmf`, except for one. Explicitly, the dependencies ar
 numpy, scipy, scitools, cosmolopy and emcee. 
 
 You will only need `emcee` if you are going to be using the fitting capabilities
-of `hmf`. The final, optional, library is pycamb. It is a bit trickier to install.
+of `hmf`.
+
+The final, optional, library is pycamb. It is a bit trickier to install.
 Please follow the guidelines on its `readme page <https://github.com/steven-murray/pycamb.git>`_.
 
 .. note:: At present, versions of CAMB post March 2013 are not working with
@@ -26,30 +50,36 @@ to install the latest build (not necessarily stable), grab it `here
 To go really bleeding edge, install the develop branch using
 ``pip install git+git://github.com/steven-murray/hmf.git@develop``.
 
-Basic Usage
------------
-`hmf` can be used interactively (for instance in ipython) or in a script and is
-called like this:
+Quickstart
+----------
+Once you have `hmf` installed, you can quickly generate a mass function
+by opening an interpreter (e.g. IPython) and doing:
 
 >>> from hmf import MassFunction
 >>> hmf = MassFunction()
 >>> mass_func = hmf.dndlnm
->>> mass_variance = hmf.sigma
->>> ...
 
-This will return a Sheth-Mo-Tormen (2001) mass function between 
-:math:`10^{10}-10^{15} M_\odot`, at :math:`z=0` for the default PLANCK cosmology. 
-Cosmological parameters may be passed to the initialiser, ``MassFunction()``
+Note that all parameters have (what I consider reasonable) defaults. In particular,
+this will return a Sheth-Mo-Tormen (2001) mass function between
+:math:`10^{10}-10^{15} M_\odot`, at :math:`z=0` for the default PLANCK15 cosmology.
+Nevertheless, there are several parameters which can be input, either cosmological
+or otherwise. The best way to see these is to do
+
+>>> MassFunction.parameter_info()
+
+We can also check which parameters have been set in our "default" instance:
+
+>>> hmf.parameter_values
 
 To change the parameters (cosmological or otherwise), one should use the 
 `update()` method, if a MassFunction() object already exists. For example
 
 >>> hmf = MassFunction()
->>> hmf.update(omegab = 0.05,z=10) #update baryon density and redshift
+>>> hmf.update(Ob0 = 0.05, z=10) #update baryon density and redshift
 >>> cumulative_mass_func = hmf.ngtm
 
-Please check the more in-depth user-guide for more details, or even the API
-documentation.
+For a more involved introduction to `hmf`, check out the `tutorials <tutorials.html>`_,
+which are currently under construction, or the `API docs <api.html>`_.
 
 
 Contents