update conversion documentation

docs/conversion.txt

@@ -7,5 +7,11 @@ E.g., sampling in chirp mass and mass ratio can be much more efficient than samp
 
 We have many functions to do this.
 
+These are used in multiple places:
+- `PriorDict`s have a `conversion_function`, for the GW PriorDicts, these are from this module.
+- `WaveformGenerator`s can use a `parameter_conversion`, again these are from this module.
+- A `conversion_function` can be passed to `run_sampler`, this is done as a post-processing step.
+For CBCs either `generate_all_bbh_parameters` or `generate_all_bns_parameters` can be used.
+
 .. automodule:: bilby.gw.conversion
     :members:
\ No newline at end of file

docs/prior-constraints.txt

+========================
+Prior Constraints
+========================
+
+Added v. 0.4.3
+
+This allows cuts to be specified in the prior space.
+
+You can provide the `PriorDict` a `conversion_function` and a set of `Constraint` priors to remove parts of the prior space.
+
+_Note_: after doing this the prior probability will not be normalised.
+
+Simple example
+
+--------------
+
+Sample from uniform distributions in two parameters x and y with the condition x >= y.
+
+First thing: define a function which generates z=x-y from x and y.
+
+```
+def convert_x_y_to_z(parameters):
+    """
+    Function to convert between sampled parameters and constraint parameter.
+
+    Parameters
+    ----------
+    parameters: dict
+        Dictionary containing sampled parameter values, 'x', 'y'.
+
+    Returns
+    -------
+    dict: Dictionary with constraint parameter 'z' added.
+    """
+    parameters['z'] = parameters['x'] - parameters['y']
+    return parameters
+```
+
+Create our prior:
+
+```
+from bilby.core.prior import PriorDict, Uniform, Constraint
+
+priors = PriorDict(conversion_function=convert_x_y_to_z)
+priors['x'] = Uniform(minimum=0, maximum=10)
+priors['y'] = Uniform(minimum=0, maximum=10)
+priors['z'] = Constraint(minimum=0, maximum=10)
+```
+
+Sample from this distribution and plot the samples.
+
+```
+import matplotlib.pyplot as plt
+
+samples = priors.sample(1000000)
+plt.hist2d(samples['x'], samples['y'], bins=100, cmap='Blues')
+plt.xlabel('$x$')
+plt.ylabel('$y$')
+plt.tight_layout()
+plt.show()
+plt.close()
+```
+
+------
+
+Gravitational wave priors
+
+We provide default conversion functions for the BBH and BNS PriorDicts.
+
+For BBHs this generates all the BBH mass parameters so constraints can be placed on any mass parameters.
+
+For BNSs it also generates the tidal deformability parameters.