Merge pull request #836 from RSE-Sheffield/package-level-info

Document at package level

.gitignore

@@ -50,3 +50,9 @@ iterate.dat
 
 # pycharm IDE stuff
 .idea/
+
+# docs
+GPy*.rst
+
+# vscode
+settings.json

.readthedocs.yml

@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: doc/source/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: 
+  - htmlzip
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: doc/source/requirements.txt

GPy/core/__init__.py

@@ -1,6 +1,30 @@
 # Copyright (c) 2012-2014, GPy authors (see AUTHORS.txt).
 # Licensed under the BSD 3-clause license (see LICENSE.txt)
 
+"""
+Introduction
+^^^^^^^^^^^^
+
+This module contains the fundamental classes of GPy - classes that are inherited by objects in other parts of GPy in order to provide a consistent interface to major functionality. 
+
+.. inheritance-diagram:: GPy.core.gp.GP
+    :top-classes: paramz.core.parameter_core.Parameterizable
+
+:py:class:`GPy.core.model` is inherited by :py:class:`GPy.core.gp.GP`. And :py:class:`GPy.core.model` itself inherits :py:class:`paramz.model.Model` from the `paramz` package. `paramz` essentially provides an inherited set of properties and functions used to manage state (and state changes) of the model.
+
+:py:class:`GPy.core.gp.GP` represents a GP model. Such an entity is typically passed variables representing known (x) and observed (y) data, along with a kernel and other information needed to create the specific model. It exposes functions which return information derived from the inputs to the model, for example predicting unobserved variables based on new known variables, or the log marginal likelihood of the current state of the model.
+
+:py:func:`~GPy.core.gp.GP.optimize` is called to optimize hyperparameters of the model. The optimizer argument takes a string which is used to specify non-default optimization schemes.
+
+Various plotting functions can be called against :py:class:`GPy.core.gp.GP`.
+
+.. inheritance-diagram:: GPy.core.gp_grid.GpGrid GPy.core.sparse_gp.SparseGP GPy.core.sparse_gp_mpi.SparseGP_MPI GPy.core.svgp.SVGP 
+    :top-classes: GPy.core.gp.GP
+
+:py:class:`GPy.core.gp.GP` is used as the basis for classes supporting more specialized types of Gaussian Process model. These are however generally still not specific enough to be called by the user and are inhereted by members of the :py:class:`GPy.models` package.
+
+"""
+
 from GPy.core.model import Model
 from .parameterization import Param, Parameterized
 from . import parameterization

GPy/core/gp.py

@@ -335,7 +335,7 @@ class GP(Model):
             of the output dimensions.
 
         Note: If you want the predictive quantiles (e.g. 95% confidence
-        interval) use :py:func:"~GPy.core.gp.GP.predict_quantiles".
+        interval) use :py:func:`~GPy.core.gp.GP.predict_quantiles`.
         """
 
         # Predict the latent function values
@@ -384,7 +384,7 @@ class GP(Model):
            If full_cov and self.input_dim > 1, the return shape of var is Nnew x Nnew x self.input_dim. If self.input_dim == 1, the return shape is Nnew x Nnew.
            This is to allow for different normalizations of the output dimensions.
 
-        Note: If you want the predictive quantiles (e.g. 95% confidence interval) use :py:func:"~GPy.core.gp.GP.predict_quantiles".
+        Note: If you want the predictive quantiles (e.g. 95% confidence interval) use :py:func:`~GPy.core.gp.GP.predict_quantiles`.
         """
         return self.predict(Xnew, full_cov, Y_metadata, kern, None, False)
 

GPy/core/parameterization/__init__.py

@@ -1,3 +1,14 @@
+"""
+Introduction
+^^^^^^^^^^^^
+
+Extends the functionality of the `paramz` package (dependency) to support paramterization of priors (:py:class:`GPy.core.parameterization.priors`).
+
+.. inheritance-diagram:: GPy.core.parameterization.priors
+   :top-classes: paramz.core.parameter_core.Parameterizable
+"""
+
+
 # Copyright (c) 2012-2014, GPy authors (see AUTHORS.txt).
 # Licensed under the BSD 3-clause license (see LICENSE.txt)
 

GPy/examples/__init__.py

@@ -1,10 +1,16 @@
 # Copyright (c) 2012-2014, GPy authors (see AUTHORS.txt).
 # Licensed under the BSD 3-clause license (see LICENSE.txt)
 """
-Examples for GPy.
+Introduction
+^^^^^^^^^^^^
 
 The examples in this package usually depend on `pods <https://github.com/sods/ods>`_ so make sure 
-you have that installed before running examples.
+you have that installed before running examples. The easiest way to do this is to run `pip install pods`. `pods` enables access to 3rd party data required for most of the examples. 
+
+The examples are executable and self-contained workflows in that they have their own source data, create their own models, kernels and other objects as needed, execute optimisation as required, and display output.
+
+Viewing the source code of each model will clarify the steps taken in its execution, and may provide inspiration for developing of user-specific applications of `GPy`.
+
 """
 from . import classification
 from . import regression

GPy/inference/__init__.py

@@ -1,3 +1,11 @@
+"""
+Introduction
+^^^^^^^^^^^^
+
+
+
+"""
+
 from . import optimization
 from . import latent_function_inference
 from . import mcmc

GPy/inference/latent_function_inference/__init__.py

@@ -1,23 +1,30 @@
 # Copyright (c) 2012-2014, Max Zwiessele, James Hensman
 # Licensed under the BSD 3-clause license (see LICENSE.txt)
 
-__doc__ = """
+"""
+Introduction
+^^^^^^^^^^^^
+
+Certain :py:class:`GPy.models` can be instanciated with an `inference_method`. This submodule contains objects that can be assigned to `inference_method`.
+
 Inference over Gaussian process latent functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In all our GP models, the consistency propery means that we have a Gaussian
+In all our GP models, the consistency property means that we have a Gaussian
-prior over a finite set of points f. This prior is
+prior over a finite set of points f. This prior is:
 
-  math:: N(f | 0, K)
+.. math:: 
+    N(f | 0, K)
 
-where K is the kernel matrix.
+where :math:`K` is the kernel matrix.
 
-We also have a likelihood (see GPy.likelihoods) which defines how the data are
+We also have a likelihood (see :py:class:`GPy.likelihoods`) which defines how the data are
-related to the latent function: p(y | f).  If the likelihood is also a Gaussian,
+related to the latent function: :math:`p(y | f)`.  If the likelihood is also a Gaussian,
-the inference over f is tractable (see exact_gaussian_inference.py).
+the inference over :math:`f` is tractable (see :py:class:`GPy.inference.latent_function_inference.exact_gaussian_inference`).
 
 If the likelihood object is something other than Gaussian, then exact inference
-is not tractable. We then resort to a Laplace approximation (laplace.py) or
+is not tractable. We then resort to a Laplace approximation (:py:class:`GPy.inference.latent_function_inference.laplace`) or
-expectation propagation (ep.py).
+expectation propagation (:py:class:`GPy.inference.latent_function_inference.expectation_propagation`).
 
 The inference methods return a
 :class:`~GPy.inference.latent_function_inference.posterior.Posterior`

GPy/kern/__init__.py

@@ -1,10 +1,26 @@
-"""
-Kernel module the kernels to sit in.
 
-.. automodule:: .src
-   :members:
-   :private-members:
 """
+Introduction
+^^^^^^^^^^^^
+
+In terms of Gaussian Processes, a kernel is a function that specifies the degree of similarity between variables given their relative positions in parameter space. If known variables *x* and *x'* are close together then observed variables *y* and *y'* may also be similar, depending on the kernel function and its parameters. *Note: this may be too simple a definition for the broad range of kernels available in :py:class:`GPy`.*
+
+:py:class:`GPy.kern.src.kern.Kern` is a generic kernel object inherited by more specific, end-user kernels used in models. It provides methods that specific kernels should generally have such as :py:class:`GPy.kern.src.kern.Kern.K` to compute the value of the kernel, :py:class:`GPy.kern.src.kern.Kern.add` to combine kernels and numerous functions providing information on kernel gradients.
+
+There are several inherited types of kernel that provide a basis for specific end user kernels:
+
+.. inheritance-diagram:: GPy.kern.src.kern.Kern GPy.kern.src.static GPy.kern.src.stationary GPy.kern.src.kern.CombinationKernel GPy.kern.src.brownian GPy.kern.src.linear GPy.kern.src.standard_periodic
+   :top-classes: GPy.core.parameterization.parameterized.Parameterized
+
+e.g. the archetype :py:class:`GPy.kern.RBF` does not inherit directly from :py:class:`GPy.kern.src.kern.Kern`, but from :py:class:`GPy.kern.src.stationary`.
+
+.. inheritance-diagram:: GPy.kern.src.kern.Kern GPy.kern.RBF
+   :top-classes: GPy.core.parameterization.parameterized.Parameterized
+
+"""
+
+
+
 from .src.kern import Kern
 from .src.add import Add
 from .src.prod import Prod

GPy/kern/src/__init__.py

@@ -1 +1,2 @@
+
 from . import psi_comp

GPy/kern/src/coregionalize.py

@@ -20,12 +20,13 @@ class Coregionalize(Kern):
     Covariance function for intrinsic/linear coregionalization models
 
     This covariance has the form:
+
     .. math::
-       \mathbf{B} = \mathbf{W}\mathbf{W}^\top + \text{diag}(kappa)
+       \mathbf{B} = \mathbf{W}\mathbf{W}^\intercal + \mathrm{diag}(kappa)
 
     An intrinsic/linear coregionalization covariance function of the form:
-    .. math::
 
+    .. math::
        k_2(x, y)=\mathbf{B} k(x, y)
 
     it is obtained as the tensor product between a covariance function

GPy/likelihoods/__init__.py

@@ -1,3 +1,16 @@
+"""
+Introduction
+^^^^^^^^^^^^
+
+The likelihood is :math:`p(y|f,X)` which is how well we will predict target values given inputs :math:`X` and our latent function :math:`f` (:math:`y` without noise). Marginal likelihood :math:`p(y|X)`, is the same as likelihood except we marginalize out the model :math:`f`. The importance of likelihoods in Gaussian Processes is in determining the 'best' values of kernel and noise hyperparamters to relate known, observed and unobserved data. The purpose of optimizing a model (e.g. :py:class:`GPy.models.GPRegression`) is to determine the 'best' hyperparameters i.e. those that minimize negative log marginal likelihood.
+
+.. inheritance-diagram:: GPy.likelihoods.likelihood GPy.likelihoods.mixed_noise.MixedNoise
+   :top-classes: GPy.core.parameterization.parameterized.Parameterized
+
+Most likelihood classes inherit directly from :py:class:`GPy.likelihoods.likelihood`, although an intermediary class :py:class:`GPy.likelihoods.mixed_noise.MixedNoise` is used by :py:class:`GPy.likelihoods.multioutput_likelihood`.
+
+"""
+
 from .bernoulli import Bernoulli
 from .exponential import Exponential
 from .gaussian import Gaussian, HeteroscedasticGaussian

GPy/models/__init__.py

@@ -1,6 +1,29 @@
 # Copyright (c) 2012, GPy authors (see AUTHORS.txt).
 # Licensed under the BSD 3-clause license (see LICENSE.txt)
 
+"""
+Introduction
+^^^^^^^^^^^^
+
+This package principally contains classes ultimately inherited from :py:class:`GPy.core.gp.GP` intended as models for end user consuption - much of :py:class:`GPy.core.gp.GP` is not intended to be called directly. The general form of a "model" is a function that takes some data, a kernel (see :py:class:`GPy.kern`) and other parameters, returning an object representation.
+
+Several models directly inherit :py:class:`GPy.core.gp.GP`:
+
+.. inheritance-diagram:: GPy.models.gp_classification GPy.models.gp_coregionalized_regression GPy.models.gp_heteroscedastic_regression GPy.models.gp_offset_regression GPy.models.gp_regression GPy.models.gp_var_gauss GPy.models.gplvm GPy.models.input_warped_gp GPy.models.multioutput_gp
+    :top-classes: GPy.core.gp.GP
+
+Some models fall into conceptually related groups of models (e.g. :py:class:`GPy.core.sparse_gp`, :py:class:`GPy.core.sparse_gp_mpi`):
+
+.. inheritance-diagram:: GPy.models.bayesian_gplvm GPy.models.bayesian_gplvm_minibatch GPy.models.gp_multiout_regression GPy.models.gp_multiout_regression_md GPy.models.ibp_lfm.IBPLFM GPy.models.sparse_gp_coregionalized_regression GPy.models.sparse_gp_minibatch GPy.models.sparse_gp_regression GPy.models.sparse_gp_regression_md GPy.models.sparse_gplvm
+    :top-classes: GPy.core.gp.GP
+
+In some cases one end-user model inherits another e.g.
+
+.. inheritance-diagram:: GPy.models.bayesian_gplvm_minibatch
+    :top-classes: GPy.models.sparse_gp_minibatch.SparseGPMiniBatch
+
+"""
+
 from .gp_regression import GPRegression
 from .gp_classification import GPClassification
 from .sparse_gp_regression import SparseGPRegression

GPy/models/gp_kronecker_gaussian_regression.py

@@ -18,14 +18,11 @@ class GPKroneckerGaussianRegression(Model):
 
     The noise must be iid Gaussian.
 
-    See Stegle et al.
+    See [stegle_et_al_2011]_.
-    @inproceedings{stegle2011efficient,
+
-      title={Efficient inference in matrix-variate gaussian models with $\\backslash$ iid observation noise},
+    .. rubric:: References
-      author={Stegle, Oliver and Lippert, Christoph and Mooij, Joris M and Lawrence, Neil D and Borgwardt, Karsten M},
+
-      booktitle={Advances in Neural Information Processing Systems},
+    .. [stegle_et_al_2011] Stegle, O.; Lippert, C.; Mooij, J.M.; Lawrence, N.D.; Borgwardt, K.:Efficient inference in matrix-variate Gaussian models with \iid observation noise. In: Advances in Neural Information Processing Systems, 2011, Pages 630-638
-      pages={630--638},
-      year={2011}
-    }
 
     """
     def __init__(self, X1, X2, Y, kern1, kern2, noise_var=1., name='KGPR'):

GPy/models/gp_multiout_regression.py

@@ -15,9 +15,11 @@ class GPMultioutRegression(SparseGP):
     """
     Gaussian Process model for multi-output regression without missing data
 
-    This is an implementation of Latent Variable Multiple Output Gaussian Processes (LVMOGP) in [Dai et al. 2017].
+    This is an implementation of Latent Variable Multiple Output Gaussian Processes (LVMOGP) in [Dai_et_al_2017]_.
 
-    Zhenwen Dai, Mauricio A. Alvarez and Neil D. Lawrence. Efficient Modeling of Latent Information in Supervised Learning using Gaussian Processes. In NIPS, 2017.
+    .. rubric:: References
+
+    .. [Dai_et_al_2017] Dai, Z.; Alvarez, M.A.; Lawrence, N.D: Efficient Modeling of Latent Information in Supervised Learning using Gaussian Processes. In NIPS, 2017.
 
     :param X: input observations.
     :type X: numpy.ndarray
@@ -42,6 +44,7 @@ class GPMultioutRegression(SparseGP):
     :param int qU_var_c_W_dim: the dimensionality of the covariance of q(U) for the GP regression. If it is smaller than the number of inducing points, it represents a low-rank parameterization of the covariance matrix.
     :param str init: the choice of initialization: 'GP' or 'rand'. With 'rand', the model is initialized randomly. With 'GP', the model is initialized through a protocol as follows: (1) fits a sparse GP (2) fits a BGPLVM based on the outcome of sparse GP (3) initialize the model based on the outcome of the BGPLVM.
     :param str name: the name of the model
+
     """
     def __init__(self, X, Y, Xr_dim, kernel=None, kernel_row=None, Z=None, Z_row=None, X_row=None, Xvariance_row=None, num_inducing=(10,10), qU_var_r_W_dim=None, qU_var_c_W_dim=None, init='GP', name='GPMR'):
 

GPy/models/gp_multiout_regression_md.py

@@ -16,9 +16,11 @@ class GPMultioutRegressionMD(SparseGP):
     """
     Gaussian Process model for multi-output regression with missing data
 
-    This is an implementation of Latent Variable Multiple Output Gaussian Processes (LVMOGP) in [Dai et al. 2017]. This model targets at the use case, in which each output dimension is observed at a different set of inputs. The model takes a different data format: the inputs and outputs observations of all the output dimensions are stacked together correspondingly into two matrices. An extra array is used to indicate the index of output dimension for each data point. The output dimensions are indexed using integers from 0 to D-1 assuming there are D output dimensions.
+    This is an implementation of Latent Variable Multiple Output Gaussian Processes (LVMOGP) in [Dai_et_al_2017]_. This model targets at the use case, in which each output dimension is observed at a different set of inputs. The model takes a different data format: the inputs and outputs observations of all the output dimensions are stacked together correspondingly into two matrices. An extra array is used to indicate the index of output dimension for each data point. The output dimensions are indexed using integers from 0 to D-1 assuming there are D output dimensions.
 
-    Zhenwen Dai, Mauricio A. Alvarez and Neil D. Lawrence. Efficient Modeling of Latent Information in Supervised Learning using Gaussian Processes. In NIPS, 2017.
+    .. rubric:: References
+
+    .. [Dai_et_al_2017] Dai, Z.; Alvarez, M.A.; Lawrence, N.D: Efficient Modeling of Latent Information in Supervised Learning using Gaussian Processes. In NIPS, 2017.
 
     :param X: input observations.
     :type X: numpy.ndarray
@@ -46,6 +48,8 @@ class GPMultioutRegressionMD(SparseGP):
     :param str init: the choice of initialization: 'GP' or 'rand'. With 'rand', the model is initialized randomly. With 'GP', the model is initialized through a protocol as follows: (1) fits a sparse GP (2) fits a BGPLVM based on the outcome of sparse GP (3) initialize the model based on the outcome of the BGPLVM.
     :param boolean heter_noise: whether assuming heteroscedastic noise in the model, boolean
     :param str name: the name of the model
+
+
     """
     def __init__(self, X, Y, indexD, Xr_dim, kernel=None, kernel_row=None,  Z=None, Z_row=None, X_row=None, Xvariance_row=None, num_inducing=(10,10), qU_var_r_W_dim=None, qU_var_c_W_dim=None, init='GP', heter_noise=False, name='GPMRMD'):
 

GPy/models/gp_var_gauss.py

@@ -13,13 +13,9 @@ class GPVariationalGaussianApproximation(GP):
     """
     The Variational Gaussian Approximation revisited
 
-    @article{Opper:2009,
+    .. rubric:: References
-        title = {The Variational Gaussian Approximation Revisited},
+
-        author = {Opper, Manfred and Archambeau, C{\'e}dric},
+    .. [opper_archambeau_2009] Opper, M.; Archambeau, C.; The Variational Gaussian Approximation Revisited. Neural Comput. 2009, pages 786-792.
-        journal = {Neural Comput.},
-        year = {2009},
-        pages = {786--792},
-    }
     """
     def __init__(self, X, Y, kernel, likelihood, Y_metadata=None):
 

GPy/models/gradient_checker.py

@@ -39,28 +39,30 @@ class GradientChecker(Model):
             a list of names with the same length is expected.
         :param args: Arguments passed as f(x, *args, **kwargs) and df(x, *args, **kwargs)
 
-        Examples:
+        .. rubric:: Examples
-        ---------
+        
+        Initialisation::
+
             from GPy.models import GradientChecker
             N, M, Q = 10, 5, 3
 
-            Sinusoid:
+        Sinusoid::
 
-                X = numpy.random.rand(N, Q)
+            X = numpy.random.rand(N, Q)
-                grad = GradientChecker(numpy.sin,numpy.cos,X,'x')
+            grad = GradientChecker(numpy.sin,numpy.cos,X,'x')
-                grad.checkgrad(verbose=1)
+            grad.checkgrad(verbose=1)
 
-            Using GPy:
+        Using GPy::
 
-                X, Z = numpy.random.randn(N,Q), numpy.random.randn(M,Q)
+            X, Z = numpy.random.randn(N,Q), numpy.random.randn(M,Q)
-                kern = GPy.kern.linear(Q, ARD=True) + GPy.kern.rbf(Q, ARD=True)
+            kern = GPy.kern.linear(Q, ARD=True) + GPy.kern.rbf(Q, ARD=True)
-                grad = GradientChecker(kern.K,
+            grad = GradientChecker(kern.K,
-                                       lambda x: 2*kern.dK_dX(numpy.ones((1,1)), x),
+                                    lambda x: 2*kern.dK_dX(numpy.ones((1,1)), x),
-                                       x0 = X.copy(),
+                                    x0 = X.copy(),
-                                       names='X')
+                                    names='X')
-                grad.checkgrad(verbose=1)
+            grad.checkgrad(verbose=1)
-                grad.randomize()
+            grad.randomize()
-                grad.checkgrad(verbose=1)
+            grad.checkgrad(verbose=1)
         """
         super(GradientChecker, self).__init__(name='GradientChecker')
         if isinstance(x0, (list, tuple)) and names is None:

GPy/plotting/__init__.py

@@ -1,3 +1,11 @@
+"""
+Introduction
+^^^^^^^^^^^^
+
+:py:class:`GPy.plotting` effectively extends models based on :py:class:`GPy.core.gp.GP` (and other classes) by adding methods to plot useful charts. 'matplotlib', 'plotly' (online) and 'plotly' (offline) are supported. The methods in :py:class:`GPy.plotting` (and child classes :py:class:`GPy.plotting.gpy_plot` and :py:class:`GPy.plotting.matplot_dep`) are not intended to be called directly, but rather are 'injected' into other classes (notably :py:class:`GPy.core.gp.GP`). Documentation describing plots is best found associated with the model being plotted e.g. :py:class:`GPy.core.gp.GP.plot_confidence`.
+
+"""
+
 # Copyright (c) 2014, GPy authors (see AUTHORS.txt).
 # Licensed under the BSD 3-clause license (see LICENSE.txt)
 current_lib = [None]

GPy/plotting/gpy_plot/latent_plots.py

@@ -89,7 +89,8 @@ def plot_latent_scatter(self, labels=None,
     Plot a scatter plot of the latent space.
 
     :param array-like labels: a label for each data point (row) of the inputs
-    :param (int, int) which_indices: which input dimensions to plot against each other
+    :param which_indices: which input dimensions to plot against each other
+    :type which_indices: (int, int)
     :param bool legend: whether to plot the legend on the figure
     :param plot_limits: the plot limits for the plot
     :type plot_limits: (xmin, xmax, ymin, ymax) or ((xmin, xmax), (ymin, ymax))
@@ -174,7 +175,8 @@ def plot_magnification(self, labels=None, which_indices=None,
     density of the GP as a gray scale.
 
     :param array-like labels: a label for each data point (row) of the inputs
-    :param (int, int) which_indices: which input dimensions to plot against each other
+    :param which_indices: which input dimensions to plot against each other
+    :type which_indices: (int, int)
     :param int resolution: the resolution at which we predict the magnification factor
     :param str marker: markers to use - cycle if more labels then markers are given
     :param bool legend: whether to plot the legend on the figure
@@ -183,7 +185,8 @@ def plot_magnification(self, labels=None, which_indices=None,
     :param bool updates: if possible, make interactive updates using the specific library you are using
     :param bool mean: use the mean of the Wishart embedding for the magnification factor
     :param bool covariance: use the covariance of the Wishart embedding for the magnification factor
-    :param :py:class:`~GPy.kern.Kern` kern: the kernel to use for prediction
+    :param kern: the kernel to use for prediction
+    :type kern: :py:class:`~GPy.kern.Kern`
     :param int num_samples: the number of samples to plot maximally. We do a stratified subsample from the labels, if the number of samples (in X) is higher then num_samples.
     :param imshow_kwargs: the kwargs for the imshow (magnification factor)
     :param kwargs: the kwargs for the scatter plots
@@ -248,13 +251,15 @@ def plot_latent(self, labels=None, which_indices=None,
     scatter plot of the input dimemsions selected by which_indices.
 
     :param array-like labels: a label for each data point (row) of the inputs
-    :param (int, int) which_indices: which input dimensions to plot against each other
+    :param which_indices: which input dimensions to plot against each other
+    :type which_indices: (int, int)
     :param int resolution: the resolution at which we predict the magnification factor
     :param bool legend: whether to plot the legend on the figure
     :param plot_limits: the plot limits for the plot
     :type plot_limits: (xmin, xmax, ymin, ymax) or ((xmin, xmax), (ymin, ymax))
     :param bool updates: if possible, make interactive updates using the specific library you are using
-    :param :py:class:`~GPy.kern.Kern` kern: the kernel to use for prediction
+    :param kern: the kernel to use for prediction
+    :type kern: :py:class:`~GPy.kern.Kern`
     :param str marker: markers to use - cycle if more labels then markers are given
     :param int num_samples: the number of samples to plot maximally. We do a stratified subsample from the labels, if the number of samples (in X) is higher then num_samples.
     :param imshow_kwargs: the kwargs for the imshow (magnification factor)
@@ -316,13 +321,15 @@ def plot_steepest_gradient_map(self, output_labels=None, data_labels=None, which
     scatter plot of the input dimemsions selected by which_indices.
 
     :param array-like labels: a label for each data point (row) of the inputs
-    :param (int, int) which_indices: which input dimensions to plot against each other
+    :param which_indices: which input dimensions to plot against each other
+    :type which_indices: (int, int)
     :param int resolution: the resolution at which we predict the magnification factor
     :param bool legend: whether to plot the legend on the figure, if int plot legend columns on legend
     :param plot_limits: the plot limits for the plot
     :type plot_limits: (xmin, xmax, ymin, ymax) or ((xmin, xmax), (ymin, ymax))
     :param bool updates: if possible, make interactive updates using the specific library you are using
-    :param :py:class:`~GPy.kern.Kern` kern: the kernel to use for prediction
+    :param kern: the kernel to use for prediction
+    :type kern: :py:class:`~GPy.kern.Kern`
     :param str marker: markers to use - cycle if more labels then markers are given
     :param int num_samples: the number of samples to plot maximally. We do a stratified subsample from the labels, if the number of samples (in X) is higher then num_samples.
     :param imshow_kwargs: the kwargs for the imshow (magnification factor)

GPy/util/__init__.py

@@ -1,6 +1,12 @@
 # Copyright (c) 2012, GPy authors (see AUTHORS.txt).
 # Licensed under the BSD 3-clause license (see LICENSE.txt)
+"""
+Introduction
+^^^^^^^^^^^^
 
+A variety of utility functions including matrix operations and quick access to test datasets.
+
+"""
 
 from . import linalg
 from . import misc

README.md

@@ -222,6 +222,13 @@ The documentation can be compiled as follows:
     sphinx-apidoc -o source/ ../GPy/
     make html
 
+alternatively:
+
+```{shell}
+cd doc
+sphinx-build -b html -d build/doctrees -D graphviz_dot='<path to dot>' source build/html
+```
+
 The HTML files are then stored in doc/build/html
 
 ### Commit new patch to devel

doc/source/conf.py

@@ -64,7 +64,7 @@ if on_rtd:
     print(out)
 
     #Lets regenerate our rst files from the source, -P adds private modules (i.e kern._src)
-    proc = subprocess.Popen("sphinx-apidoc -P -f -o . ../../GPy", stdout=subprocess.PIPE, shell=True)
+    proc = subprocess.Popen("sphinx-apidoc -M -P -f -o . ../../GPy", stdout=subprocess.PIPE, shell=True)
     (out, err) = proc.communicate()
     print("$ Apidoc:")
     print(out)
@@ -83,8 +83,13 @@ extensions = [
     #'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'sphinx.ext.graphviz',
+    'sphinx.ext.inheritance_diagram',
 ]
 
+#---sphinx.ext.inheritance_diagram config
+inheritance_graph_attrs = dict(rankdir="LR", dpi=1200)
+
 #----- Autodoc
 #import sys
 #try:
@@ -134,7 +139,7 @@ master_doc = 'index'
 project = u'GPy'
 #author = u'`Humans <https://github.com/SheffieldML/GPy/graphs/contributors>`_'
 author = 'GPy Authors, see https://github.com/SheffieldML/GPy/graphs/contributors'
-copyright = u'2015, '+author
+copyright = u'2020, '+author
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -245,6 +250,10 @@ html_theme = 'sphinx_rtd_theme'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_css_files = [
+    'wide.css',
+]
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.

doc/source/index.rst

@@ -1,48 +1,90 @@
-.. GPy documentation master file, created by
+GPy - A Gaussian Process (GP) framework in Python
-   sphinx-quickstart on Fri Sep 18 18:16:28 2015.
+=================================================
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to GPy's documentation!
+Introduction
-===============================
+------------
 
-`GPy <http://sheffieldml.github.io/GPy/>`_ is a Gaussian Process (GP) framework written in Python, from the Sheffield machine learning group.
+`GPy <http://sheffieldml.github.io/GPy/>`_ is a Gaussian Process (GP) framework written in Python, from the Sheffield machine learning group. It includes support for basic GP regression, multiple output GPs (using coregionalization), various noise models, sparse GPs, non-parametric regression and latent variables.
 
 The `GPy homepage <http://sheffieldml.github.io/GPy/>`_ contains tutorials for users and further information on the project, including installation instructions.
-This documentation is mostly aimed at developers interacting closely with the code-base.
+
+The documentation hosted here is mostly aimed at developers interacting closely with the code-base.
+
+Source Code
+-----------
 
 The code can be found on our `Github project page <https://github.com/SheffieldML/GPy>`_. It is open source and provided under the BSD license.
 
-For developers:
+Installation
+------------
 
-- `Writing new models <tuto_creating_new_models.html>`_
+Installation instructions can currently be found on our `Github project page <https://github.com/SheffieldML/GPy>`_.
-- `Writing new kernels <tuto_creating_new_kernels.html>`_
-- `Write a new plotting routine using gpy_plot <tuto_plotting.html>`_
-- `Parameterization handles <tuto_parameterized.html>`_
 
-Contents:
+Tutorials
+---------
+
+Several tutorials have been developed in the form of `Jupyter Notebooks <https://nbviewer.jupyter.org/github/SheffieldML/notebook/blob/master/GPy/index.ipynb>`_. 
+
+Architecture
+------------
+
+GPy is a big, powerful package, with many features. The concept of how to use GPy in general terms is roughly as follows. A model (:py:class:`GPy.models`) is created - this is at the heart of GPy from a user perspective. A kernel (:py:class:`GPy.kern`), data and, usually, a representation of noise are assigned to the model. Specific models require, or can make use of, additional information. The kernel and noise are controlled by hyperparameters - calling the optimize (:py:class:`GPy.core.gp.GP.optimize`) method against the model invokes an iterative process which seeks optimal hyperparameter values. The model object can be used to make plots and predictions (:py:class:`GPy.core.gp.GP.predict`).
+
+.. graphviz::
+
+   digraph GPy_Arch {
+      
+      rankdir=LR
+      node[shape="rectangle" style="rounded,filled" fontname="Arial"]
+      edge [color="#006699" len=2.5]
+
+      Data->Model
+      Hyperparameters->Kernel
+      Hyperparameters->Noise
+      Kernel->Model
+      Noise->Model
+      
+      Model->Optimize
+      Optimize->Hyperparameters
+      
+      Model->Predict
+      Model->Plot
+      
+      Optimize [shape="ellipse"]
+      Predict [shape="ellipse"]
+      Plot [shape="ellipse"]
+      
+      subgraph cluster_0 {
+         Data
+         Kernel
+         Noise
+      }
+
+   }
 
 .. toctree::
    :maxdepth: 1
+   :caption: For developers
 
+   tuto_creating_new_models
+   tuto_creating_new_kernels
+   tuto_plotting
+   tuto_parameterized
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API Documentation
+
+   GPy.core
+   GPy.core.parameterization
    GPy.models
    GPy.kern
    GPy.likelihoods
    GPy.mappings
    GPy.examples
    GPy.util
-   GPy.plotting.gpy_plot
+   GPy.plotting
-   GPy.plotting.matplot_dep
-   GPy.core
-   GPy.core.parameterization
    GPy.inference.optimization
    GPy.inference.latent_function_inference
    GPy.inference.mcmc
-	      
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`