Improved type hints in documentation

docs/source/conf.py

@@ -12,14 +12,15 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
-
 from datetime import datetime
 import os
 from pathlib import Path
 import sys
 
 from pkg_resources import DistributionNotFound, get_distribution
 
+import probnum
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -55,19 +56,8 @@
 autodoc_typehints_description_target = "all"
 autodoc_typehints_format = "short"
 autodoc_type_aliases = {
-    "ShapeType": "typing.ShapeType",
-    "ScalarType": "typing.ScalarType",
-    "MatrixType": "typing.MatrixType",
-    "IntLike": "typing.IntLike",
-    "FloatLike": "typing.FloatLike",
-    "ShapeLike": "typing.ShapeLike",
-    "DTypeLike": "typing.DTypeLike",
-    "ArrayIndicesLike": "typing.ArrayIndicesLike",
-    "ScalarLike": "typing.ScalarLike",
-    "ArrayLike": "typing.ArrayLike",
-    "LinearOperatorLike": "typing.LinearOperatorLike",
-    "NotImplementedType": "typing.NotImplementedType",
-}
+    type_alias: f"typing.{type_alias}" for type_alias in probnum.typing.__all__
+}  # Ensures type aliases are correctly displayed and linked in the documentation
 
 # Settings for napoleon
 napoleon_use_param = True
@@ -157,7 +147,7 @@
     "python": ("https://docs.python.org/3/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy", None),
-    "matplotlib": ("https://matplotlib.org/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
 }
 
 # -- Options for HTML output ----------------------------------------------

src/probnum/randprocs/_random_process.py

@@ -41,7 +41,7 @@ class RandomProcess(Generic[InputType, OutputType], abc.ABC):
     --------
     ~probnum.randvars.RandomVariable : Random variables.
     ~probnum.randprocs.GaussianProcess : Gaussian processes.
-    ~probnum.randprocs.markov.MarkovProcess : Random processes with the Markov property.
+    ~probnum.randprocs.markov.MarkovProcess : Random processes with the Maqrkov property.
 
     Notes
     -----

src/probnum/randvars/_constant.py

@@ -1,4 +1,5 @@
-"""(Almost surely) constant random variables."""
+"""Random variables that are constant (with probability one)."""
+
 from __future__ import annotations
 
 from functools import cached_property

src/probnum/typing.py

@@ -3,14 +3,18 @@
 This module defines commonly used types in the library. These are separated into two
 different kinds, API types and argument types.
 
-API types are aliases which define custom types used throughout the library. Objects of
+**API types** (``*Type``) are aliases which define custom types used throughout the library. Objects of
 this type may be supplied as arguments or returned by a method.
 
-Argument types are aliases which define commonly used method arguments. These should
-only ever be used in the signature of a method and then be converted internally, e.g.
-in a class instantiation or an interface. They enable the user to conveniently
-specify a variety of object types for the same argument, while ensuring a unified
-internal representation of those same objects.
+**Argument types** (``*Like``) are aliases which define commonly used method
+arguments that are internally converted to a standardized representation. These should only
+ever be used in the signature of a method and then be converted internally, e.g. in a class
+instantiation or an interface. They enable the user to conveniently
+supply a variety of objects of different types for the same argument, while ensuring a unified
+internal representation of those same objects. As an example, take the different ways a user might
+specify a shape: ``2``, ``(2,)``, ``[2, 2]``. These may all be acceptable arguments to a function
+taking a shape, but internally should always be converted to a :attr:`ShapeType`, i.e. a tuple of
+``int``\\ s.
 """
 
 from __future__ import annotations
@@ -60,28 +64,28 @@
 
 # Python Numbers
 IntLike = Union[int, numbers.Integral, np.integer]
-"""Type of a public API argument for supplying an integer.
+"""Object that can be converted to an integer.
 
-Values of this type should always be converted into :class:`int`\\ s before further
-internal processing."""
+Arguments of type :attr:`IntLike` should always be converted into :class:`int`\\ s before
+further internal processing."""
 
 FloatLike = Union[float, numbers.Real, np.floating]
-"""Type of a public API argument for supplying a float.
+"""Object that can be converted to a float.
 
-Values of this type should always be converteg into :class:`float`\\ s before further
+Arguments of type :attr:`FloatLike` should always be converteg into :class:`float`\\ s before further
 internal processing."""
 
 # Array Utilities
 ShapeLike = Union[IntLike, Iterable[IntLike]]
-"""Type of a public API argument for supplying a shape.
+"""Object that can be converted to a shape.
 
-Values of this type should always be converted into :class:`ShapeType` using the
+Arguments of type :attr:`ShapeLike` should always be converted into :class:`ShapeType` using the
 function :func:`probnum.utils.as_shape` before further internal processing."""
 
 DTypeLike = _NumPyDTypeLike
-"""Type of a public API argument for supplying an array's dtype.
+"""Object that can be converted to an array dtype.
 
-Values of this type should always be converted into :class:`numpy.dtype`\\ s before further
+Arguments of type :attr:`DTypeLike` should always be converted into :class:`numpy.dtype`\\ s before further
 internal processing."""
 
 _ArrayIndexLike = Union[
@@ -93,31 +97,33 @@
     np.ndarray,
 ]
 ArrayIndicesLike = Union[_ArrayIndexLike, Tuple[_ArrayIndexLike, ...]]
-"""Type of the argument to the :meth:`__getitem__` method of a NumPy-like array type
+"""Object that can be converted to indices of an array.
+
+Type of the argument to the :meth:`__getitem__` method of a NumPy-like array type
 such as :class:`numpy.ndarray`, :class:`probnum.linops.LinearOperator` or
 :class:`probnum.randvars.RandomVariable`."""
 
 # Scalars, Arrays and Matrices
 ScalarLike = Union[int, float, complex, numbers.Number, np.number]
-"""Type of a public API argument for supplying a scalar value.
+"""Object that can be converted to a scalar value.
 
-Values of this type should always be converted into :class:`numpy.number`\\ s using the
+Arguments of type :attr:`ScalarLike` should always be converted into :class:`numpy.number`\\ s using the
 function :func:`probnum.utils.as_scalar` before further internal processing."""
 
 ArrayLike = _NumPyArrayLike
-"""Type of a public API argument for supplying an array.
+"""Object that can be converted to an array.
 
-Values of this type should always be converted into :class:`numpy.ndarray`\\ s using
+Arguments of type :attr:`ArrayLike` should always be converted into :class:`numpy.ndarray`\\ s using
 the function :func:`np.asarray` before further internal processing."""
 
 LinearOperatorLike = Union[
     ArrayLike,
     scipy.sparse.spmatrix,
     "probnum.linops.LinearOperator",
 ]
-"""Type of a public API argument for supplying a finite-dimensional linear operator.
+"""Object that can be converted to a :class:`~probnum.linops.LinearOperator`.
 
-Values of this type should always be converted into :class:`probnum.linops.\\
+Arguments of type :attr:`LinearOperatorLike` should always be converted into :class:`~probnum.linops.\\
 LinearOperator`\\ s using the function :func:`probnum.linops.aslinop` before further
 internal processing."""