docs nice

docs/source/conf.py

@@ -193,4 +193,8 @@ def setup(app):
 intersphinx_mapping = {
     'pint': ('https://pint.readthedocs.io/en/0.11/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'uncertainties': ('https://uncertainties-python-package.readthedocs.io/en/latest/', None),
+    'dynesty': ('https://dynesty.readthedocs.io/en/latest/', None),
+    'emcee': ('https://emcee.readthedocs.io/en/stable/', None),
 }
+

uravu/optimize.py

@@ -1,36 +1,27 @@
 """
-The optimize module includes the functionality necessary for maximum
-likelihood determination. Further, the natural log likelihood function used
-in the ``mcmc`` and ``nested_sampling`` methods may be found here.
+The optimize module includes the functionality necessary for maximum likelihood determination. 
+Furthermore, the natural log likelihood function used in the :func:`~uravu.sampling.mcmc()` and :func:`~uravu.sampling.nested_sampling()` methods may be found here.
 """
 
 # Copyright (c) Andrew R. McCluskey
 # Distributed under the terms of the MIT License
 # author: Andrew R. McCluskey
 
 import numpy as np
-import uncertainties
 from scipy.optimize import minimize
 from uncertainties import unumpy as unp
 
 
 def max_ln_likelihood(relationship, x0=None, **kwargs):
     """
-    Determine the variable values which maximize the likelihood for the
-    given relationship. For keyword arguments see the
-    `scipy.optimize.minimize()`_ documentation.
+    Determine the variable values which maximize the likelihood for the given relationship. For keyword arguments see the :func:`scipy.optimize.minimize()` documentation.
 
     Args:
-        relationship (uravu.relationship.Relationship): The relationship for
-            which variables should be found.
-        x0 (array_like, optional): Initial guesses for the variable values.
-            Default to the current ``relationship.variables`` values which
-            are initialized as all ones.
+        relationship (:py:class:`uravu.relationship.Relationship`): The relationship for which variables should be found.
+        x0 (:py:attr:`array_like`, optional): Initial guesses for the variable values. Default to the current :py:attr:`~uravu.relationship.Relationship.variables` values which are initialized as all :py:attr:`1`.
 
     Return:
-        (array_like): optimized variables for the relationship.
-
-    .. _scipy.optimize.minimize(): https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html
+        :py:attr:`array_like`: Optimized variables for the relationship.
     """
     if x0 is None:
         x0 = relationship.variable_medians
@@ -51,19 +42,17 @@ def negative_lnl(
     variables, function, abscissa, ordinate, unaccounted_uncertainty=False
 ):
     """
-    Calculate the negative natural logarithm of the likelihood given a set
-    of variables, when there is no uncertainty in the abscissa.
+    Calculate the negative natural logarithm of the likelihood given a set of variables, when there is no uncertainty in the abscissa.
 
     Args:
-        variables (array_like): Variables for the function evaluation.
-        function (callable): The function to be evaluated.
-        abscissa (array_like): The abscissa values.
-        ordinate (array_like): The ordinate values.
-        unaccounted_uncertainty (bool, optional): Should an unaccounted
-            uncertainty parameter be considered. Default is ``False``.
+        variables (:py:attr:`array_like`): Variables for the function evaluation.
+        function (:py:attr:`callable`): The function to be evaluated.
+        abscissa (:py:attr:`array_like`): The abscissa values.
+        ordinate (:py:attr:`array_like`): The ordinate values.
+        unaccounted_uncertainty (:py:attr:`bool`, optional): Should an unaccounted uncertainty parameter be considered. Default is :py:attr:`False`.
 
     Returns:
-        (float): Negative ln-likelihood between model and data.
+        :py:attr:`float`: Negative natural log-likelihood between model and data.
     """
     return -ln_likelihood(
         variables,
@@ -78,19 +67,17 @@ def ln_likelihood(
     variables, function, abscissa, ordinate, unaccounted_uncertainty=False
 ):
     """
-    Calculate the natural logarithm of the likelihood given a set of
-    variables, when there is no uncertainty in the abscissa.
+    Calculate the natural logarithm of the likelihood given a set of variables, when there is no uncertainty in the abscissa.
 
     Args:
-        variables (array_like): Variables for the function evaluation.
-        function (callable): The function to be evaluated.
-        abscissa (array_like): The abscissa values.
-        ordinate (array_like): The ordinate values.
-        unaccounted_uncertainty (bool, optional): Should an unaccounted
-            uncertainty parameter be considered. Default is ``False``.
+        variables (:py:attr:`array_like`): Variables for the function evaluation.
+        function (:py:attr:`callable`): The function to be evaluated.
+        abscissa (:py:attr:`array_like`): The abscissa values.
+        ordinate (:py:attr:`array_like`): The ordinate values.
+        unaccounted_uncertainty (:py:attr:`bool`, optional): Should an unaccounted uncertainty parameter be considered. Default is :py:attr:`False`.
 
     Returns:
-        (float): ln-likelihood between model and data.
+         :py:attr:`float`: Natural log-likelihood between model and data.
     """
     if unaccounted_uncertainty:
         var = variables[:-1]

uravu/plotting.py

@@ -1,10 +1,7 @@
 """
-These are plotting functions that take either :class:`Relationship`
-or :class:`Distribution` class objects.
+These are plotting functions that take either :py:class:`~uravu.relationship.Relationship` or :py:class:`~uravu.distribution.Distribution` class objects.
 
-The aim is to produce *publication quality* plots. However, we
-recognise that taste exists, and ours may be different from yours.
-The colorscheme in this work was chosen to be colorblind friendly.
+The aim is to produce *publication quality* plots. However, we recognise that taste exists, and ours may be different from yours. The colorscheme in this work was chosen to be colorblind friendly.
 """
 
 # Copyright (c) Andrew R. McCluskey
@@ -28,19 +25,15 @@ def plot_relationship(
     relationship, axes=None, figsize=(10, 6)
 ):  # pragma: no cover
     """
-    Plot the relationship. Additional plots will be included on this if
-    the MCMC sampling has been used to find distributions.
+    Plot the relationship. Additional plots will be included on this if the MCMC sampling has been used to find distributions.
 
     Args:
-        relationship (uravu.relationship.Relationship): The relationship to
-            be plotted.
-        axes (matplotlib.axes): Axes to which the plot should be added.
-            If none given new axes will be created.
-        fig_size (tuple, optional): horizontal and veritcal size for
-            figure (in inches). Default is `(10, 6)`.
+        relationship (:py:class:`uravu.relationship.Relationship`): The relationship to be plotted.
+        axes (:py:class:`matplotlib.axes.Axes`): Axes to which the plot should be added. If none given new axes will be created.
+        fig_size (:py:attr:`tuple`, optional): horizontal and veritcal size for figure (in inches). Default is :py:attr:`(10, 6)`.
 
     Returns:
-        (matplotlib.axes): The axes with new plots.
+        (:py:class:`matplotlib.axes.Axes`): The axes with new plots.
     """
     if axes is None:
         axes = plt.subplots(figsize=figsize)[1]
@@ -116,13 +109,11 @@ def plot_distribution(distro, axes=None, figsize=(10, 6)):  # pragma: no cover
     Plot the probability density function for a distribution.
 
     Args:
-        distro (uravu.distriobution.Distribution): The distribution to be
-            plotted.
-        fig_size (tuple): Horizontal and veritcal size for figure
-            (in inches).
+        distro (:py:class`uravu.distriobution.Distribution`): The distribution to be plotted.
+        fig_size (:py:class:`tuple`): Horizontal and veritcal size for figure (in inches). Default is :py:attr:`(10, 6)`.
 
     Returns:
-        (matplotlib.axes): The axes with new plots.
+        (:py:class:`matplotlib.axes.Axes`): The axes with new plots.
     """
     if axes is None:
         axes = plt.subplots(figsize=figsize)[1]
@@ -158,15 +149,13 @@ def plot_corner(relationship, figsize=(8, 8)):  # pragma: no cover
     relationships variables.
 
     Args:
-        relationship (uravu.relationship.Relationship): The relationship
-            containing the distributions to be plotted.
-        fig_size (tuple, optional): horizontal and veritcal size for
-            figure (in inches). Default is `(10, 6)`.
+        relationship (:py:class:`uravu.relationship.Relationship`): The relationship containing the distributions to be plotted.
+        fig_size (:py:attr:`tuple`, optional): horizontal and veritcal size for figure (in inches). Default is :py:attr:`(10, 6)`.
 
     Returns:
-        (tuple): Tuple consisting of:
-            - (matplotlib.figure): The figure with new plots.
-            - (matplotlib.axes): The axes with new plots.
+        :py:attr:`tuple`: Containing:
+            - (:py:class:`matplotlib.figure.Figure`): The figure with new plots.
+            - (:py:class:`matplotlib.axes.Axes`): The axes with new plots.
     """
     n = len(relationship.variables)
     if not all(