Add pymultinest, fix ptemcee and fix references

Also rejigs the installation to a more sensible ordering

docs/conf.py

@@ -31,7 +31,7 @@ sys.path.insert(0, os.path.abspath('../bilby/'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'numpydoc',
-              'nbsphinx', 'sphinx.ext.autosummary']
+              'nbsphinx', 'sphinx.ext.autosummary', 'sphinx.ext.autosectionlabel']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/installation.txt

@@ -31,12 +31,10 @@ Clone the repository, install the requirements, and then install the software:
    $ git clone git@git.ligo.org:lscsoft/bilby.git
    $ cd bilby/
    $ pip install -r requirements.txt
-   $ pip install -r optional_requirements.txt
    $ python setup.py install
 
-Once you have run these steps, you have :code:`bilby` installed. You can now try to
-run the examples. You should install the `optional_requirements.txt` if you
-plan to use `bilby` for gravitational wave inference.
+Once you have run these steps, you have :code:`bilby` installed. You can now
+try to run the examples.
 
 .. note::
    If you do not have a git.ligo account, and recieve an error message:
@@ -54,6 +52,21 @@ plan to use `bilby` for gravitational wave inference.
 
 .. _installing-python:
 
+Installing optional requirements
+================================
+
+The `requirements.txt
+<https://git.ligo.org/lscsoft/bilby/blob/master/requirements.txt>`_ is a
+minimal set of requirements for using :code:`bilby`. Additionally, we provide:
+
+1.  `optional_requirements.txt
+<https://git.ligo.org/lscsoft/bilby/blob/master/optional_requirements.txt>`_
+which you should install if you plan to use :code:`bilby` for
+gravitational-wave data analysis.
+
+2. By default, we only require the default sampler dynesty_ be installed. For
+instructions on installing other samplers, see :ref:`Installing samplers`.
+
 Installing python
 -----------------
 
@@ -138,40 +151,6 @@ account and SSH keys set up. Then,
 Warning: in the configure line here, we have disabled everything except
 lalsimulation. If you need other modules, see `./configure --help`.
 
-Installing pymultinest
-----------------------
-
-If you want to use the `pymultinest` sampler, you first need the
-MultiNest library to be installed to work properly. The full instructions can
-be found here: https://johannesbuchner.github.io/PyMultiNest/install.html. Here
-is a shortened version:
-
-First, install the dependencies (for Ubuntu/Linux):
-
-.. code-block:: console
-
-   $ sudo apt-get install python-{scipy,numpy,matplotlib,progressbar} ipython libblas{3,-dev} liblapack{3,-dev} libatlas{3-base,-dev} cmake build-essential git gfortran
-
-For Mac, the advice in the instructions are "If you google for “MultiNest Mac OSX” or “PyMultiNest Mac OSX” you will find installation instructions".
-
-The following will place a directory `MultiNest` in your :code:`$HOME` directory, if you want
-to place it somewhere, adjust the instructions as such.
-
-.. code-block:: console
-
-   $ git clone https://github.com/JohannesBuchner/MultiNest $HOME
-   $ cd $HOME/MultiNest/build
-   $ cmake ..
-   $ make
-
-Finally, add the libraries to you path. Add this to the `.bashrc` file
-
-.. code-block:: console
-
-   $ export LD_LIBRARY_PATH=$HOME/Downloads/MultiNest/lib:
-
-(you'll need to resource your `.bashrc` after this, i.e. run `bash`).
-
 Common problems: multiple bilby versions
 ----------------------------------------
 

docs/likelihood.txt

-.. _likelihood:
-
 ==========
 Likelihood
 ==========

docs/prior.txt

-.. _priors:
-
 ======
 Priors
 ======

docs/samplers.txt

@@ -17,15 +17,25 @@ This can be accessed via :code:`bilby.run_sampler` or
 Switching between samplers
 --------------------------
 
-:code:`bilby` includes a large number (and growing) of off-the-shelf samplers.
+:code:`bilby` can use a large number (and growing) of off-the-shelf samplers.
 Given your likelihood and prior, it is trivial to switch between samplers by
-changing the argument :code:`sampler` given to :code:`run_sampler`. Different
-samplers take different arguments to control their behaviour. To handle this,
-we allow the user to pass arbitrary `keyword arguments <https://docs.python.org/2/tutorial/controlflow.html#keyword-arguments>`_ into code:`run_sampler`. To document what keyword arguments are available,
-below we give the API for each sampler. In each of these, there is an "Other
-Parameters" section which contains information on all the available keyword
-arguments that sampler takes. For example, to use the dynesty_ sampler with
-250 live points, you would use
+changing the argument :code:`sampler` given to :code:`run_sampler`.
+
+.. note::
+   By default, only the :code:`dynesty` sampler is a requirement when
+   installing :code:`bilby`; therefore, other samplers may not be installed
+   on your system. You can try to use them, if they aren't installed a help
+   message will print out. See `installing samplers`_ for help with
+   installation.
+
+Different samplers take different arguments to control their behaviour. To
+handle this, we allow the user to pass arbitrary `keyword arguments
+<https://docs.python.org/2/tutorial/controlflow.html#keyword-arguments>`_ into
+code:`run_sampler`. To document what keyword arguments are available, below we
+give the API for each sampler. In each of these, there is an "Other Parameters"
+section which contains information on all the available keyword arguments that
+sampler takes. For example, to use the dynesty_ sampler with 250 live points,
+you would use
 
 .. code-block:: python
 
@@ -61,6 +71,11 @@ CPNest
 
 .. autoclass:: bilby.core.sampler.cpnest.Cpnest
 
+PyMultinest
+===========
+
+.. autoclass:: bilby.core.sampler.pymultinest.Pymultinest
+
 -------------
 MCMC samplers
 -------------
@@ -73,9 +88,73 @@ Emcee
 PTEmcee
 =======
 
-.. autoclass:: bilby.core.sampler.emcee.Emcee
+.. autoclass:: bilby.core.sampler.ptemcee.Ptemcee
 
 pymc3
 =====
 
 .. autoclass:: bilby.core.sampler.pymc3.Pymc3
+
+
+-------------------
+Installing samplers
+-------------------
+
+pip-installable samplers
+========================
+
+Most samplers can be installed using `pip <https://pypi.org/project/pip/>`_
+(see exceptions below). E.g., to install the :code:`emcee`
+
+.. code:: console
+
+   $ pip install emcee
+
+If you installed :code:`bilby` from source, then all the samplers can be
+installed using
+
+.. code:: console
+
+   $ pip install -r sampler_requirements.txt
+
+where the file `sampler_requirements.txt
+<https://git.ligo.org/lscsoft/bilby/blob/master/sampler_requirements.txt>`_ can
+be found in the at the top-level of `the repository
+<https://git.ligo.org/lscsoft/bilby>`_ (Note: if you installed from pip, you
+can simply download that file and use the command above).
+
+Installing pymultinest
+======================
+
+If you want to use the `pymultinest` sampler, you first need the
+MultiNest library to be installed to work properly. The full instructions can
+be found here: https://johannesbuchner.github.io/PyMultiNest/install.html. Here
+is a shortened version:
+
+First, install the dependencies (for Ubuntu/Linux):
+
+.. code-block:: console
+
+   $ sudo apt-get install python-{scipy,numpy,matplotlib,progressbar} ipython libblas{3,-dev} liblapack{3,-dev} libatlas{3-base,-dev} cmake build-essential git gfortran
+
+For Mac, the advice in the instructions are "If you google for “MultiNest Mac OSX” or “PyMultiNest Mac OSX” you will find installation instructions".
+
+The following will place a directory `MultiNest` in your :code:`$HOME` directory, if you want
+to place it somewhere, adjust the instructions as such.
+
+.. code-block:: console
+
+   $ git clone https://github.com/JohannesBuchner/MultiNest $HOME
+   $ cd $HOME/MultiNest/build
+   $ cmake ..
+   $ make
+
+Finally, add the libraries to you path. Add this to the `.bashrc` file
+
+.. code-block:: console
+
+   $ export LD_LIBRARY_PATH=$HOME/Downloads/MultiNest/lib:
+
+(you'll need to resource your `.bashrc` after this, i.e. run `bash`).
+
+