Merge pull request #331 from Thomas-Christie/kernel-notebook

Add introductory kernel notebook and change style file path in notebooks
JaxGaussianProcesses · Jul 10, 2023 · ce40904 · ce40904
2 parents d4a6969 + 2aae866
commit ce40904
Show file tree

Hide file tree

Showing 23 changed files with 825 additions and 64 deletions.
diff --git a/docs/_static/gpjax.mplstyle b/docs/_static/gpjax.mplstyle
@@ -0,0 +1,54 @@
+figure.figsize: 5.5, 2.5
+figure.constrained_layout.use: True
+figure.autolayout: False
+savefig.bbox: tight
+figure.dpi: 120
+
+# Axes
+axes.spines.left: True  # display axis spines
+axes.spines.bottom: True
+axes.spines.top: False
+axes.spines.right: False
+axes.grid: true
+axes.axisbelow: true
+
+### Fonts
+mathtext.fontset: cm
+font.family: serif
+font.serif: Computer Modern Roman
+font.size: 10
+text.usetex: True
+
+# Axes ticks
+ytick.left: True
+xtick.bottom: True
+xtick.direction: out
+ytick.direction: out
+
+# Colour palettes
+axes.prop_cycle: cycler('color', ['2F83B4','B5121B', 'F77F00', '0B6E4F', '7A68A6', 'C5BB36', '8c564b', 'e377c2'])
+lines.color: B5121B
+scatter.marker: x
+image.cmap: inferno
+
+### Grids
+grid.linestyle: -
+grid.linewidth: 0.2
+grid.color: cbcbcb
+
+### Legend
+legend.frameon: True
+legend.loc: best
+legend.fontsize: 8
+legend.fancybox: True
+legend.scatterpoints: 1
+legend.numpoints: 1
+
+patch.antialiased: True
+
+# set text objects edidable in Adobe Illustrator
+pdf.fonttype: 42
+ps.fonttype: 42
+
+# no background
+savefig.transparent: True
diff --git a/docs/examples/README.md b/docs/examples/README.md
@@ -1,44 +1,47 @@
 # Where to find the docs
 
-The GPJax documentation can be found here:
-https://docs.jaxgaussianprocesses.com/
+The GPJax documentation can be found here: https://docs.jaxgaussianprocesses.com/
 
 # How to build the docs
 
-1. Install the requirements using `pip install -r docs/requirements.txt`
+1. Ensure you have installed the requirements using `poetry install` in the root
+   directory.
 2. Make sure `pandoc` is installed
-3. Run the make script `make html`
+3. Run the command `poetry run mkdocs serve` in the root directory.
 
-The corresponding HTML files can then be found in `docs/_build/html/`.
+The documentation will then be served at an IP address printed, which can then be opened
+in a browser of you choice e.g. `Serving on http://127.0.0.1:8000/`.
 
 # How to write code documentation
 
-Our documentation it is written in ReStructuredText for Sphinx. This is a
-meta-language that is compiled into online documentation. For more details see
-[Sphinx's documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html).
-As a result, our docstrings adhere to a specific syntax that has to be kept in
-mind. Below we provide some guidelines.
+Our documentation is generated using [MkDocs](https://www.mkdocs.org/). This
+automatically creates online documentation from docstrings, with full support for
+Markdown. Longer tutorial-style notebooks are also converted to webpages by MkDocs, with
+these notebooks being stored in the `docs/examples` directory. If you write a new
+notebook and wish to add it to the documentation website, add it to the `nav` section of
+the `mkdocs.yml` file found in the root directory.
+
+Below we provide some guidelines for writing docstrings.
 
 ## How much information to put in a docstring
 
-A docstring should be informative. If in doubt, then it is best to add more
-information to a docstring than less. Many users will skim documentation, so
-please ensure the opening sentence or two of a docstring contains the core
-information. Adding examples and mathematical descriptions to documentation is
-highly desirable.
+A docstring should be informative. If in doubt, then it is best to add more information
+to a docstring than less. Many users will skim documentation, so please ensure the
+opening sentence or two of a docstring contains the core information. Adding examples
+and mathematical descriptions to documentation is highly desirable.
 
-We are making an active effort within GPJax to improve our documentation. If you
-spot any areas where there is missing information within the existing
-documentation, then please either raise an issue or
-[create a pull request](https://docs.jaxgaussianprocesses.com/contributing/).
+We are making an active effort within GPJax to improve our documentation. If you spot
+any areas where there is missing information within the existing documentation, then
+please either raise an issue or [create a pull
+request](https://docs.jaxgaussianprocesses.com/contributing/).
 
 ## An example docstring
 
-An example docstring that adheres the principles of GPJax is given below.
-The docstring contains a simple, snappy introduction with links to auxiliary
-components. More detail is then provided in the form of a mathematical
-description and a code example. The docstring is concluded with a description
-of the objects attributes with corresponding types.
+An example docstring that adheres the principles of GPJax is given below. The docstring
+contains a simple, snappy introduction with links to auxiliary components. More detail
+is then provided in the form of a mathematical description and a code example. The
+docstring is concluded with a description of the objects attributes with corresponding
+types.
 
 ```python
 from gpjax.gps import AbstractPrior
@@ -53,16 +56,11 @@ class Prior(AbstractPrior):
     [mean](https://docs.jaxgaussianprocesses.com/api/mean_functions/)
     and [kernel](https://docs.jaxgaussianprocesses.com/api/kernels/base/) function.
 
-    A Gaussian process prior parameterised by a mean function :math:`m(\\cdot)` and a kernel
-    function :math:`k(\\cdot, \\cdot)` is given by
-
-    .. math::
-
-        p(f(\\cdot)) = \mathcal{GP}(m(\\cdot), k(\\cdot, \\cdot)).
+    A Gaussian process prior parameterised by a mean function $`m(\cdot)`$ and a kernel
+    function $`k(\cdot, \cdot)`$ is given by
+    $`p(f(\cdot)) = \mathcal{GP}(m(\cdot), k(\cdot, \cdot))`$.
 
-    To invoke a ``Prior`` distribution, only a kernel function is required. By default,
-    the mean function will be set to zero. In general, this assumption will be reasonable
-    assuming the data being modelled has been centred.
+    To invoke a `Prior` distribution, a kernel and mean function must be specified.
 
     Example:
         >>> import gpjax as gpx
@@ -84,10 +82,13 @@ class Prior(AbstractPrior):
 
 ### Documentation syntax
 
-A helpful cheatsheet for writing restructured text can be found
-[here](https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst). In addition to that, we adopt the following convention when documenting
-`` objects.
+We adopt the following convention when documenting objects:
 
 *  Class attributes should be specified using the `Attributes:` tag.
 *  Method argument should be specified using the `Args:` tags.
-*  All attributes and arguments should have types.
+*  Values returned by a method should be specified using the `Returns:` tag.
+*  All attributes, arguments and returned values should have types.
+
+!!! attention "Note"
+
+    Inline math in docstrings needs to be rendered within both `$` and `` symbols to be correctly rendered by MkDocs. For instance, where one would typically write `$k(x,y)$` in standard LaTeX, in docstrings you are required to write ``$`k(x,y)`$`` in order for the math to be correctly rendered by MkDocs.
diff --git a/docs/examples/barycentres.py b/docs/examples/barycentres.py
@@ -34,7 +34,9 @@
 
 
 key = jr.PRNGKey(123)
-plt.style.use("./gpjax.mplstyle")
+plt.style.use(
+    "https://github.com/raw/JaxGaussianProcesses/GPJax/main/docs/examples/gpjax.mplstyle"
+)
 cols = plt.rcParams["axes.prop_cycle"].by_key()["color"]
 
 # %% [markdown]

diff --git a/docs/examples/classification.py b/docs/examples/classification.py
@@ -52,7 +52,9 @@
 tfd = tfp.distributions
 identity_matrix = jnp.eye
 key = jr.PRNGKey(123)
-plt.style.use("./gpjax.mplstyle")
+plt.style.use(
+    "https://github.com/raw/JaxGaussianProcesses/GPJax/main/docs/examples/gpjax.mplstyle"
+)
 cols = plt.rcParams["axes.prop_cycle"].by_key()["color"]
 
 # %% [markdown]

diff --git a/docs/examples/collapsed_vi.py b/docs/examples/collapsed_vi.py
@@ -44,7 +44,9 @@
     import gpjax as gpx
 
 key = jr.PRNGKey(123)
-plt.style.use("./gpjax.mplstyle")
+plt.style.use(
+    "https://github.com/raw/JaxGaussianProcesses/GPJax/main/docs/examples/gpjax.mplstyle"
+)
 cols = mpl.rcParams["axes.prop_cycle"].by_key()["color"]
 
 # %% [markdown]

diff --git a/docs/examples/kernels.py → docs/examples/constructing_new_kernels.py b/docs/examples/kernels.py → docs/examples/constructing_new_kernels.py
@@ -46,7 +46,9 @@
 
 key = jr.PRNGKey(123)
 tfb = tfp.bijectors
-plt.style.use("./gpjax.mplstyle")
+plt.style.use(
+    "https://github.com/raw/JaxGaussianProcesses/GPJax/main/docs/examples/gpjax.mplstyle"
+)
 cols = plt.rcParams["axes.prop_cycle"].by_key()["color"]
 
 # %% [markdown]

diff --git a/docs/examples/deep_kernels.py b/docs/examples/deep_kernels.py
@@ -45,7 +45,9 @@
     from gpjax.kernels.computations import AbstractKernelComputation
 
 key = jr.PRNGKey(123)
-plt.style.use("./gpjax.mplstyle")
+plt.style.use(
+    "https://github.com/raw/JaxGaussianProcesses/GPJax/main/docs/examples/gpjax.mplstyle"
+)
 cols = mpl.rcParams["axes.prop_cycle"].by_key()["color"]
 
 # %% [markdown]

diff --git a/docs/examples/graph_kernels.py b/docs/examples/graph_kernels.py
@@ -28,7 +28,9 @@
     import gpjax as gpx
 
 key = jr.PRNGKey(123)
-plt.style.use("./gpjax.mplstyle")
+plt.style.use(
+    "https://github.com/raw/JaxGaussianProcesses/GPJax/main/docs/examples/gpjax.mplstyle"
+)
 cols = mpl.rcParams["axes.prop_cycle"].by_key()["color"]
 
 # %% [markdown]

diff --git a/docs/examples/intro_to_gps.py b/docs/examples/intro_to_gps.py
@@ -109,7 +109,9 @@
 import tensorflow_probability.substrates.jax as tfp
 from docs.examples.utils import confidence_ellipse
 
-plt.style.use("./gpjax.mplstyle")
+plt.style.use(
+    "https://github.com/raw/JaxGaussianProcesses/GPJax/main/docs/examples/gpjax.mplstyle"
+)
 cols = mpl.rcParams["axes.prop_cycle"].by_key()["color"]
 tfd = tfp.distributions