docs/source/development/adding_to_the_api_documentation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Adding to the API Documentation\n",
    "\n",
    "Documentation is an integral part of every collaborative software project. Good documentation not only encourages users of the package to try out different functionalities, but it also makes maintaining and expanding code significantly easier. Every code contribution to the package must come with appropriate documentation of the API. This guide details how to do this."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Docstrings\n",
    "\n",
    "The main form of documentation are docstrings, multi-line comments beneath a class or function definition with a specific syntax, which detail its functionality. This package uses the\n",
    "[NumPy docstring format](https://numpydoc.readthedocs.io/en/latest/format.html#numpydoc-docstring-guide>). As a rule, all functions which are exposed to the user *must* have appropriate docstrings. Below is an example of a docstring for a probabilistic numerical method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# %load -s problinsolve ../../../src/probnum/linalg/linearsolvers/linearsolvers.py\n",
    "def problinsolve(\n",
    "    A: SquareLinOp,\n",
    "    b: RandomVecMat,\n",
    "    A0: Optional[SquareLinOp] = None,\n",
    "    Ainv0: Optional[SquareLinOp] = None,\n",
    "    x0: Optional[RandomVecMat] = None,\n",
    "    assume_A: str = \"sympos\",\n",
    "    maxiter: Optional[int] = None,\n",
    "    atol: float = 10 ** -6,\n",
    "    rtol: float = 10 ** -6,\n",
    "    callback: Optional[Callable] = None,\n",
    "    **kwargs\n",
    ") -> Tuple[\n",
    "    \"probnum.RandomVariable\", \"probnum.RandomVariable\", \"probnum.RandomVariable\", Dict\n",
    "]:\n",
    "    \"\"\"\n",
    "    Infer a solution to the linear system :math:`A x = b` in a Bayesian framework.\n",
    "\n",
    "    Probabilistic linear solvers infer solutions to problems of the form\n",
    "\n",
    "    .. math:: Ax=b,\n",
    "\n",
    "    where :math:`A \\\\in \\\\mathbb{R}^{n \\\\times n}` and :math:`b \\\\in \\\\mathbb{R}^{n}`.\n",
    "    They return a probability measure which quantifies uncertainty in the output arising\n",
    "    from finite computational resources. This solver can take prior information either\n",
    "    on the linear operator :math:`A` or its inverse :math:`H=A^{-1}` in the form of a\n",
    "    random variable ``A0`` or ``Ainv0`` and outputs a posterior belief over :math:`A` or\n",
    "    :math:`H`. This code implements the method described in Wenger et al. [1]_ based on\n",
    "    the work in Hennig et al. [2]_.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    A :\n",
    "        *shape=(n, n)* -- A square linear operator (or matrix). Only matrix-vector\n",
    "        products :math:`v \\\\mapsto Av` are used internally.\n",
    "    b :\n",
    "        *shape=(n, ) or (n, nrhs)* -- Right-hand side vector, matrix or random\n",
    "        variable in :math:`A x = b`. For multiple right hand sides, ``nrhs`` problems\n",
    "        are solved sequentially with the posteriors over the matrices acting as priors\n",
    "        for subsequent solves. If the right-hand-side is assumed to be noisy, every\n",
    "        iteration of the solver samples a realization from ``b``.\n",
    "    A0 :\n",
    "        *shape=(n, n)* -- A square matrix, linear operator or random variable\n",
    "        representing the prior belief over the linear operator :math:`A`. If an array or\n",
    "        linear operator is given, a prior distribution is chosen automatically.\n",
    "    Ainv0 :\n",
    "        *shape=(n, n)* -- A square matrix, linear operator or random variable\n",
    "        representing the prior belief over the inverse :math:`H=A^{-1}`. This can be\n",
    "        viewed as taking the form of a pre-conditioner. If an array or linear operator\n",
    "        is given, a prior distribution is chosen automatically.\n",
    "    x0 :\n",
    "        *shape=(n, ) or (n, nrhs)* -- Prior belief for the solution of the linear\n",
    "        system. Will be ignored if ``Ainv0`` is given.\n",
    "    assume_A :\n",
    "        Assumptions on the linear operator which can influence solver choice and\n",
    "        behavior. The available options are (combinations of)\n",
    "\n",
    "        ====================  =========\n",
    "         generic matrix       ``gen``\n",
    "         symmetric            ``sym``\n",
    "         positive definite    ``pos``\n",
    "         (additive) noise     ``noise``\n",
    "        ====================  =========\n",
    "\n",
    "    maxiter :\n",
    "        Maximum number of iterations. Defaults to :math:`10n`, where :math:`n` is the\n",
    "        dimension of :math:`A`.\n",
    "    atol :\n",
    "        Absolute convergence tolerance.\n",
    "    rtol :\n",
    "        Relative convergence tolerance.\n",
    "    callback :\n",
    "        User-supplied function called after each iteration of the linear solver. It is\n",
    "        called as ``callback(xk, Ak, Ainvk, sk, yk, alphak, resid, **kwargs)`` and can\n",
    "        be used to return quantities from the iteration. Note that depending on the\n",
    "        function supplied, this can slow down the solver considerably.\n",
    "    kwargs : optional\n",
    "        Optional keyword arguments passed onto the solver iteration.\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    x :\n",
    "        Approximate solution :math:`x` to the linear system. Shape of the return matches\n",
    "        the shape of ``b``.\n",
    "    A :\n",
    "        Posterior belief over the linear operator.\n",
    "    Ainv :\n",
    "        Posterior belief over the linear operator inverse :math:`H=A^{-1}`.\n",
    "    info :\n",
    "        Information on convergence of the solver.\n",
    "\n",
    "    Raises\n",
    "    ------\n",
    "    ValueError\n",
    "        If size mismatches detected or input matrices are not square.\n",
    "    LinAlgError\n",
    "        If the matrix ``A`` is singular.\n",
    "    LinAlgWarning\n",
    "        If an ill-conditioned input ``A`` is detected.\n",
    "\n",
    "    Notes\n",
    "    -----\n",
    "    For a specific class of priors the posterior mean of :math:`x_k=Hb` coincides with\n",
    "    the iterates of the conjugate gradient method. The matrix-based view taken here\n",
    "    recovers the solution-based inference of :func:`bayescg` [3]_.\n",
    "\n",
    "    References\n",
    "    ----------\n",
    "    .. [1] Wenger, J. and Hennig, P., Probabilistic Linear Solvers for Machine Learning,\n",
    "       2020\n",
    "    .. [2] Hennig, P., Probabilistic Interpretation of Linear Solvers, *SIAM Journal on\n",
    "       Optimization*, 2015, 25, 234-260\n",
    "    .. [3] Bartels, S. et al., Probabilistic Linear Solvers: A Unifying View,\n",
    "       *Statistics and Computing*, 2019\n",
    "\n",
    "    See Also\n",
    "    --------\n",
    "    bayescg : Solve linear systems with prior information on the solution.\n",
    "\n",
    "    Examples\n",
    "    --------\n",
    "    >>> import numpy as np\n",
    "    >>> np.random.seed(1)\n",
    "    >>> n = 20\n",
    "    >>> A = np.random.rand(n, n)\n",
    "    >>> A = 0.5 * (A + A.T) + 5 * np.eye(n)\n",
    "    >>> b = np.random.rand(n)\n",
    "    >>> x, A, Ainv, info = problinsolve(A=A, b=b)\n",
    "    >>> print(info[\"iter\"])\n",
    "    9\n",
    "    \"\"\"\n",
    "\n",
    "    # Check linear system for type and dimension mismatch\n",
    "    _check_linear_system(A=A, b=b, A0=A0, Ainv0=Ainv0, x0=x0)\n",
    "\n",
    "    # Check matrix assumptions for correctness\n",
    "    assume_A = assume_A.lower()\n",
    "    _assume_A_tmp = assume_A\n",
    "    for allowed_str in [\"gen\", \"sym\", \"pos\", \"noise\"]:\n",
    "        _assume_A_tmp = _assume_A_tmp.replace(allowed_str, \"\")\n",
    "    if _assume_A_tmp != \"\":\n",
    "        raise ValueError(\n",
    "            \"Assumption '{}' contains unrecognized linear operator properties.\".format(\n",
    "                assume_A\n",
    "            )\n",
    "        )\n",
    "\n",
    "    # Transform the linear system to an appropriate form\n",
    "    A, b, x0 = _preprocess_linear_system(A=A, b=b, x0=x0)\n",
    "\n",
    "    # Parameter initialization\n",
    "    n = A.shape[0]\n",
    "    nrhs = b.shape[1]\n",
    "    x = x0\n",
    "    info = {}\n",
    "\n",
    "    # Set convergence parameters\n",
    "    if maxiter is None:\n",
    "        maxiter = n * 10\n",
    "\n",
    "    if nrhs > 1:\n",
    "        # Iteratively solve for multiple right hand sides (with posteriors as new\n",
    "        # priors)\n",
    "        for i in range(nrhs):\n",
    "            if i > 0:\n",
    "                x = None  # Only use prior information on Ainv for multiple rhs\n",
    "            # Select and initialize solver\n",
    "            linear_solver = _init_solver(\n",
    "                A=A,\n",
    "                b=utils.as_colvec(b[:, i]),\n",
    "                A0=A0,\n",
    "                Ainv0=Ainv0,\n",
    "                x0=x,\n",
    "                assume_A=assume_A,\n",
    "            )\n",
    "\n",
    "            # Solve linear system\n",
    "            x, A0, Ainv0, info = linear_solver.solve(\n",
    "                maxiter=maxiter, atol=atol, rtol=rtol, callback=callback, **kwargs\n",
    "            )\n",
    "\n",
    "        # Return Ainv @ b for multiple rhs\n",
    "        x = Ainv0 @ b\n",
    "    else:\n",
    "        # Single right hand side\n",
    "        linear_solver = _init_solver(\n",
    "            A=A, b=b, A0=A0, Ainv0=Ainv0, x0=x, assume_A=assume_A\n",
    "        )\n",
    "\n",
    "        # Solve linear system\n",
    "        x, A0, Ainv0, info = linear_solver.solve(\n",
    "            maxiter=maxiter, atol=atol, rtol=rtol, callback=callback, **kwargs\n",
    "        )\n",
    "\n",
    "    # Check result and issue warnings (e.g. singular or ill-conditioned matrix)\n",
    "    _postprocess(info=info, A=A)\n",
    "\n",
    "    return x, A0, Ainv0, info\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**General Rules**\n",
    "\n",
    "- Cover `Parameters`, `Returns`, `Raises` and `Examples`, if applicable, in every publicly visible docstring---in that order.\n",
    "- Examples are tested via doctest. Ensure `doctest` does not fail by running the test suite.\n",
    "- Include appropriate `References`, in particular for probabilistic numerical methods.\n",
    "- Do not use docstrings as a clutch for spaghetti code!\n",
    "\n",
    "**Parameters**\n",
    "\n",
    "- Parameter types are automatically documented via type hints in the function signature.\n",
    "- Always provide shape hints for objects with a `.shape` attribute in the following form:\n",
    "\n",
    "```python\n",
    "\"\"\"\n",
    "Parameters\n",
    "----------\n",
    "arr :\n",
    "    *(shape=(m, ) or (m, n))* -- Parameter array of an example function.\n",
    "\"\"\"\n",
    "```\n",
    "\n",
    "- Hyperparameters should have default values and explanations on how to choose them.\n",
    "- For callables provide the expected signature as part of the docstring: `foobar(x, y, z, \\*\\*kwargs)`. Backslashes remove semantic meaning from special characters.\n",
    "\n",
    "**Style**\n",
    "\n",
    "- Stick to the imperative style of writing in the docstring header (i.e.: first line).\n",
    "  - Yes: \"Compute the value\". \n",
    "  - No: \"This function computes the value / Let's compute the value\".\n",
    "  \n",
    "  The rest of the explanation talks about the function, e. g. \"This function computes the value by computing another value\".\n",
    "- Use full sentences inside docstrings when describing something.\n",
    "  - Yes: \"This value is irrelevant, because it is not being passed on\"\n",
    "  - No: \"Value irrelevant, not passed on\". \n",
    "- When in doubt, more explanation rather than less. A little text inside an example can be helpful, too.\n",
    "- A little maths can go a long way, but too much usually adds confusion."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interface Documentation\n",
    "\n",
    "\n",
    "Which functions and classes actually show up in the documentation is determined by an `__all__` statement in the corresponding `__init__.py` file inside a module. The order of this list is also reflected in the documentation. For example, `linalg` has the following `__init__.py`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# %load ../../../src/probnum/linalg/__init__.py\n",
    "\"\"\"\n",
    "Linear Algebra.\n",
    "\n",
    "This package implements common operations and (probabilistic) numerical methods for\n",
    "linear algebra.\n",
    "\"\"\"\n",
    "\n",
    "from probnum.linalg.linearsolvers import *\n",
    "\n",
    "# Public classes and functions. Order is reflected in documentation.\n",
    "__all__ = [\n",
    "    \"problinsolve\",\n",
    "    \"bayescg\",\n",
    "    \"ProbabilisticLinearSolver\",\n",
    "    \"MatrixBasedSolver\",\n",
    "    \"AsymmetricMatrixBasedSolver\",\n",
    "    \"SymmetricMatrixBasedSolver\",\n",
    "    \"SolutionBasedSolver\",\n",
    "]\n",
    "\n",
    "# Set correct module paths. Corrects links and module paths in documentation.\n",
    "ProbabilisticLinearSolver.__module__ = \"probnum.linalg\"\n",
    "MatrixBasedSolver.__module__ = \"probnum.linalg\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you are documenting a subclass, which has a different path in the file structure than the import path due to `__all__` statements, you can correct the links to superclasses in the documentation via the `.__module__` attribute."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sphinx\n",
    "\n",
    "ProbNum uses [Sphinx](https://www.sphinx-doc.org/en/master/) to parse docstrings in the codebase automatically and to create its API documentation. You can configure Sphinx itself or its extensions in the `./docs/conf.py` file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "nbsphinx-thumbnail": {
     "output-index": 0
    },
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.display import Image\n",
    "\n",
    "display(Image(filename=\"../img/developer_guides/sphinx_logo.png\", embed=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "ProbNum makes use of a number of Sphinx plugins to improve the API documentation, for example to parse this Jupyter notebook. The full list of currently used packages is listed below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# %load ../../requirements.txt\n",
    "# Sphinx builds the documentation\n",
    "sphinx>=3.0\n",
    "\n",
    "# Sphinx extensions\n",
    "sphinx-rtd-theme\n",
    "sphinx-automodapi\n",
    "sphinx-autodoc-typehints\n",
    "sphinx-gallery\n",
    "\n",
    "# Markdown conversion\n",
    "m2r2\n",
    "\n",
    "# Jupyter notebooks\n",
    "nbsphinx\n",
    "jupyter\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building and Viewing the Documentation\n",
    "\n",
    "In order to build the documentation locally and view the HTML version of the API documentation, simply run: \n",
    "```bash\n",
    "tox -e docs\n",
    "```\n",
    "This creates a static web page under `./docs/_build/html/` which you can view in your browser by opening \n",
    "`./docs/_build/html/intro.html`.\n",
    "\n",
    "Alternatively, if you want to build the docs in your current environment you can manually execute\n",
    "```bash\n",
    "cd docs\n",
    "make clean\n",
    "make html\n",
    "```\n",
    "\n",
    "For more information on `tox`, check out the [general development instructions](../development/contributing.rst)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}