Merge pull request #137 from thomaspinder/docs_improve

Update docs

docs/README.md

@@ -0,0 +1,86 @@
+# Where to find the docs
+
+The GPJax documentation can be found here:
+https://gpjax.readthedocs.io/en/latest/
+
+# How to build the docs
+
+1. Install the requirements using `pip install -r docs/requirements.txt`
+2. Make sure `pandoc` is installed
+3. Run the make script `make html`
+
+The corresponding HTML files can then be found in `docs/_build/html/`.
+
+# 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.
+
+## 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.
+
+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://gpjax.readthedocs.io/en/latest/contributing.html).
+
+## 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 auxillary 
+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
+@dataclass
+class Prior(AbstractPrior):
+    """A Gaussian process prior object. The GP is parameterised by a
+    `mean <https://gpjax.readthedocs.io/en/latest/api.html#module-gpjax.mean_functions>`_
+    and `kernel <https://gpjax.readthedocs.io/en/latest/api.html#module-gpjax.kernels>`_ 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)).
+
+    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.
+
+    Example:
+        >>> import gpjax as gpx
+        >>>
+        >>> kernel = gpx.kernels.RBF()
+        >>> prior = gpx.Prior(kernel = kernel)
+
+    Attributes:
+        kernel (Kernel): The kernel function used to parameterise the prior.
+        mean_function (MeanFunction): The mean function used to parameterise the prior. Defaults to zero.
+        name (str): The name of the GP prior. Defaults to "GP prior".
+    """
+
+    kernel: Kernel
+    mean_function: Optional[AbstractMeanFunction] = Zero()
+    name: Optional[str] = "GP prior"
+```
+
+### 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
+`dataclass` 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.

docs/_api.rst

@@ -8,34 +8,63 @@ Package Reference
 Gaussian Processes
 #################################
 
+The Gaussian process abstractions in GPJax can be segmented into two distinct
+types: prior and posterior objects. This makes for a clean separation of both
+code and mathematical concepts. Throught the multiplication of a
+`Prior <https://gpjax.readthedocs.io/en/latest/api.html#gaussian-process-priors>`_
+and `Likelihood <https://gpjax.readthedocs.io/en/latest/api.html#module-gpjax.likelihoods>`_,
+GPJax will then return the appropriate `Posterior <https://gpjax.readthedocs.io/en/latest/api.html#gaussian-process-posteriors>`_.
+
+
 .. automodule:: gpjax.gps
 .. currentmodule:: gpjax.gps
 
-
 Abstract GPs
 *********************************
 
-.. autoclass:: AbstractGP
+To ensure a consistent API, we subclass all Gaussian process objects from either
+``AbstractPrior`` or ``AbstractPosterior``. These classes are not intended to be
+used directly, but instead to provide a common interface for all downstream Gaussian
+process objects.
+
+.. autoclass:: AbstractPrior
    :members:
+   :special-members: __call__
+   :private-members: _initialise_params
+   :exclude-members: from_tuple, replace, to_tuple
 
 .. autoclass:: AbstractPosterior
    :members:
+   :special-members: __call__
 
 
 Gaussian Process Priors
 *********************************
 
 .. autoclass:: Prior
    :members:
+   :special-members: __call__, __mul__
 
 Gaussian Process Posteriors
 *********************************
 
+There are two main classes of posterior Gaussian process objects within GPJax.
+The ``ConjugatePosterior`` class is used when the likelihood distribution is
+Gaussian whilst the ``NonConjugatePosterior`` class is used when the likelihood
+distribution is non-Gaussian.
+
 .. autoclass:: ConjugatePosterior
    :members:
+   :special-members: __call__
 
 .. autoclass:: NonConjugatePosterior
    :members:
+   :special-members: __call__
+
+Posterior Constructors
+*********************************
+
+.. autofunction:: construct_posterior
 
 
 Kernels
@@ -54,7 +83,7 @@ Kernel Functions
 Abstract Kernels
 *********************************
 
-.. autoclass:: Kernel
+.. autoclass:: AbstractKernel
    :members:
 
 .. autoclass:: CombinationKernel

docs/_static/css/gpjax_theme.css

@@ -0,0 +1,3 @@
+nav .bd-links a:hover{
+    color: #B5121B
+}

docs/_templates/autosummary/gpjax_module.rst

@@ -0,0 +1,23 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :exclude-members:
+
+   {% block methods %}
+
+   .. automethod:: __call__
+
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+
+   {% for item in methods %}
+   {%- if item not in inherited_members and item not in annotations and not item in ['__init__'] %}
+       ~{{ name }}.{{ item }}
+   {%- endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/conf.py

@@ -16,9 +16,11 @@
 import re
 import sys
 
+sys.path.insert(0, os.path.abspath(".."))
+
 from importlib_metadata import version
 
-# sys.path.insert(0, os.path.abspath("../.."))
+import docs.conf_sphinx_patch
 
 
 def read(*names, **kwargs):
@@ -72,14 +74,16 @@ def find_version(*file_paths):
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
-    "sphinx.ext.autosectionlabel",
     "sphinx_copybutton",
     "sphinxcontrib.bibtex",
     "sphinxext.opengraph",
     "myst_parser",
     "sphinx_tabs.tabs",
 ]
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 # MyST Config
 myst_enable_extensions = [
     "amsmath",
@@ -165,6 +169,15 @@ def find_version(*file_paths):
 ]
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
+master_doc = "index"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]
+html_static_path = ["_static"]
+html_css_files = ["css/gpjax_theme.css"]
+
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -173,14 +186,14 @@ def find_version(*file_paths):
 
 
 autosummary_generate = True
+autodoc_typehints = "none"
 napoleon_use_rtype = False
 autodoc_default_options = {
     "member-order": "bysource",
     "special-members": "__init__, __call__",
-    "undoc-members": True,
-    "exclude-members": "__weakref__,_abc_impl",
+    "exclude-members": "__weakref__,_abc_impl,from_tuple,replace,to_tuple",
+    "autodoc-typehints": "none",
 }
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -202,22 +215,5 @@ def find_version(*file_paths):
     "use_repository_button": True,
     "use_sidenotes": True,  # Turns footnotes into sidenotes - https://sphinx-book-theme.readthedocs.io/en/stable/content-blocks.html
 }
-# html_title = f"v{version}"
-# html_theme_options = {
-#     "light_css_variables": {
-#         "color-brand-primary": "#B5121B",
-#         "color-brand-content": "#CC3333",
-#         "color-admonition-background": "orange",
-#         "source_repository": "https://github.com/thomaspinder/GPJax/",
-#         "source_branch": "master",
-#         "source_directory": "docs/",
-#     },
-# }
 
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
-html_static_path = ["_static"]
-html_css_files = ["custom.css"]
+always_document_param_types = True