Run pydocstyle in pre-commit (#6382)

* Run `pydocstyle` in pre-commit
* Remove pydocstyle settings from `setup.cfg`

Includes docstring formatting to reduce the number of error codes
that had to be silenced for pydocstyle to be happy.

Closes #6378

.pre-commit-config.yaml

@@ -35,6 +35,14 @@ repos:
       args: [--rcfile=.pylintrc]
       files: ^pymc/
       exclude: (?x)(pymc/_version.py)
+- repo: https://github.com/PyCQA/pydocstyle
+  rev: 6.1.1
+  hooks:
+    - id: pydocstyle
+      args:
+      - --ignore=D100,D101,D102,D103,D104,D105,D107,D200,D202,D203,D204,D205,D209,D212,D213,D301,D400,D401,D403,D413,D415,D417
+      files: ^pymc/
+      exclude: ^pymc/tests/
 - repo: https://github.com/MarcoGorelli/madforhooks
   rev: 0.3.0
   hooks:

pymc/blocking.py

@@ -79,7 +79,7 @@ def rmap(
         """Map 1D concatenated array to a dictionary of variables in their original spaces.
 
         Parameters
-        ==========
+        ----------
         array
             The array to map.
         start_point

pymc/distributions/continuous.py

@@ -1593,7 +1593,6 @@ class LogNormal(PositiveContinuous):
 
     Examples
     --------
-
     .. code-block:: python
 
         # Example to show that we pass in only ``sigma`` or ``tau`` but not both.

pymc/distributions/discrete.py

@@ -1549,7 +1549,6 @@ class OrderedLogistic:
 
     Examples
     --------
-
     .. code-block:: python
 
         # Generate data for a simple 1 dimensional example problem

pymc/distributions/dist_math.py

@@ -355,17 +355,19 @@ def grad(self, inp, grads):
 def random_choice(p, size):
     """Return draws from categorical probability functions
 
-    Args:
-        p: array
-           Probability of each class. If p.ndim > 1, the last axis is
-           interpreted as the probability of each class, and numpy.random.choice
-           is iterated for every other axis element.
-        size: int or tuple
-            Shape of the desired output array. If p is multidimensional, size
-            should broadcast with p.shape[:-1].
-
-    Returns:
-        random sample: array
+    Parameters
+    ----------
+    p : array
+        Probability of each class. If p.ndim > 1, the last axis is
+        interpreted as the probability of each class, and numpy.random.choice
+        is iterated for every other axis element.
+    size : int or tuple
+        Shape of the desired output array. If p is multidimensional, size
+        should broadcast with p.shape[:-1].
+
+    Returns
+    -------
+    random_sample : array
 
     """
     k = p.shape[-1]

pymc/distributions/distribution.py

@@ -413,7 +413,7 @@ def _get_measurable_outputs_symbolic_random_variable(op, node):
 @node_rewriter([SymbolicRandomVariable])
 def inline_symbolic_random_variable(fgraph, node):
     """
-    This optimization expands the internal graph of a SymbolicRV when obtaining the logp
+    Optimization that expands the internal graph of a SymbolicRV when obtaining the logp
     graph, if the flag `inline_logprob` is True.
     """
     op = node.op
@@ -828,7 +828,6 @@ class CustomDist:
 
     Examples
     --------
-
     Create a CustomDist that wraps a black-box logp function. This variable cannot be
     used in prior or posterior predictive sampling because no random function was provided
 

pymc/distributions/multivariate.py

@@ -796,7 +796,6 @@ class OrderedMultinomial:
 
     Examples
     --------
-
     .. code-block:: python
 
         # Generate data for a simple 1 dimensional example problem

pymc/distributions/transforms.py

@@ -240,7 +240,6 @@ class Interval(IntervalTransform):
 
     Examples
     --------
-
     Create an interval transform between -1 and +1
 
     .. code-block:: python

pymc/distributions/truncated.py

@@ -30,8 +30,10 @@
 
 
 class TruncatedRV(SymbolicRandomVariable):
-    """An `Op` constructed from an PyTensor graph that represents a truncated univariate
-    random variable."""
+    """
+    An `Op` constructed from an PyTensor graph
+    that represents a truncated univariate random variable.
+    """
 
     default_output = 1
     base_rv_op = None

pymc/gp/util.py

@@ -188,7 +188,7 @@ def plot_gp_dist(
 ):
     """A helper function for plotting 1D GP posteriors from trace
 
-        Parameters
+    Parameters
     ----------
     ax: axes
         Matplotlib axes.
@@ -213,7 +213,6 @@ def plot_gp_dist(
 
     Returns
     -------
-
     ax: Matplotlib axes
     """
     import matplotlib.pyplot as plt

pymc/logprob/abstract.py

@@ -194,7 +194,7 @@ def assign_custom_measurable_outputs(
     `factorized_joint_logprob`.
 
     Parameters
-    ==========
+    ----------
     node
         The node to recreate with a new cloned `Op`.
     measurable_outputs_fn

pymc/logprob/joint_logprob.py

@@ -95,7 +95,7 @@ def factorized_joint_logprob(
 
 
     Parameters
-    ==========
+    ----------
     rv_values
         A ``dict`` of variables that maps stochastic elements
         (e.g. `RandomVariable`\s) to symbolic `Variable`\s representing their
@@ -111,7 +111,7 @@ def factorized_joint_logprob(
         etc.)
 
     Returns
-    =======
+    -------
     A ``dict`` that maps each value variable to the log-probability factor derived
     from the respective `RandomVariable`.
 

pymc/logprob/rewriting.py

@@ -67,7 +67,7 @@
 
 
 class NoCallbackEquilibriumDB(EquilibriumDB):
-    r"""This `EquilibriumDB` doesn't hide its exceptions.
+    r"""An `EquilibriumDB` that doesn't hide its exceptions.
 
     By setting `failure_callback` to ``None`` in the `EquilibriumGraphRewriter`\s
     that `EquilibriumDB` generates, we're able to directly emit the desired
@@ -102,7 +102,7 @@ class PreserveRVMappings(Feature):
     def __init__(self, rv_values: Dict[TensorVariable, TensorVariable]):
         """
         Parameters
-        ==========
+        ----------
         rv_values
             Mappings between random variables and their value variables.
             The keys of this map are what this `Feature` keeps updated.
@@ -130,7 +130,7 @@ def update_rv_maps(
         original value variables.
 
         Parameters
-        ==========
+        ----------
         old_rv
             The random variable whose mappings will be updated.
         new_value

pymc/logprob/scan.py

@@ -79,7 +79,7 @@ def convert_outer_out_to_in(
     r"""Convert outer-graph outputs into outer-graph inputs.
 
     Parameters
-    ==========
+    ----------
     input_scan_args:
         The source `Scan` arguments.
     outer_out_vars:
@@ -253,7 +253,7 @@ def get_random_outer_outputs(
     """Get the `MeasurableVariable` outputs of a `Scan` (well, its `ScanArgs`).
 
     Returns
-    =======
+    -------
     A tuple of tuples containing the index of each outer-output variable, the
     outer-output variable itself, and the inner-output variable that
     is an instance of `MeasurableVariable`.
@@ -329,7 +329,7 @@ def create_inner_out_logp(value_map: Dict[TensorVariable, TensorVariable]) -> Te
 
 @node_rewriter([Scan])
 def find_measurable_scans(fgraph, node):
-    r"""Finds `Scan`\s for which a `logprob` can be computed.
+    r"""Find `Scan`\s for which a `logprob` can be computed.
 
     This will convert said `Scan`\s into `MeasurableScan`\s.  It also updates
     random variable and value variable mappings that have been specified for

pymc/logprob/transforms.py

@@ -295,7 +295,7 @@ def __init__(
     ):
         """
         Parameters
-        ==========
+        ----------
         values_to_transforms
             Mapping between value variables and their transformations.  Each
             value variable can be assigned one of `RVTransform`, or ``None``.
@@ -514,7 +514,7 @@ def __init__(self, args_fn: Callable[..., Tuple[Optional[Variable], Optional[Var
         """
 
         Parameters
-        ==========
+        ----------
         args_fn
             Function that expects inputs of RandomVariable and returns the lower
             and upper bounds for the interval transformation. If one of these is
@@ -660,7 +660,7 @@ def _create_transformed_rv_op(
     also behaving exactly as it did before.
 
     Parameters
-    ==========
+    ----------
     rv_op
         The `RandomVariable` for which we want to construct a `TransformedRV`.
     transform

pymc/logprob/utils.py

@@ -62,7 +62,7 @@ def walk_model(
     By default, these walks will not go past ``MeasurableVariable`` nodes.
 
     Parameters
-    ==========
+    ----------
     graphs
         The graphs to walk.
     walk_past_rvs
@@ -104,12 +104,12 @@ def replace_rvs_in_graphs(
     This will *not* recompute test values.
 
     Parameters
-    ==========
+    ----------
     graphs
         The graphs in which random variables are to be replaced.
 
     Returns
-    =======
+    -------
     A ``tuple`` containing the transformed graphs and a ``dict`` of the
     replacements that were made.
     """
@@ -154,7 +154,7 @@ def rvs_to_value_vars(
     This will *not* recompute test values in the resulting graphs.
 
     Parameters
-    ==========
+    ----------
     graphs
         The graphs in which to perform the replacements.
     initial_replacements

pymc/math.py

@@ -196,7 +196,7 @@ def kron_matrix_op(krons, m, op):
     r"""Apply op to krons and m in a way that reproduces ``op(kronecker(*krons), m)``
 
     Parameters
-    -----------
+    ----------
     krons : list of square 2D array-like objects
         D square matrices :math:`[A_1, A_2, ..., A_D]` to be Kronecker'ed
         :math:`A = A_1 \otimes A_2 \otimes ... \otimes A_D`

pymc/model.py

@@ -153,7 +153,7 @@ class ContextMeta(type):
     """
 
     def __new__(cls, name, bases, dct, **kwargs):  # pylint: disable=unused-argument
-        "Add __enter__ and __exit__ methods to the class."
+        """Add __enter__ and __exit__ methods to the class."""
 
         def __enter__(self):
             self.__class__.context_class.get_contexts().append(self)
@@ -457,7 +457,6 @@ class Model(WithMemoization, metaclass=ContextMeta):
 
     Examples
     --------
-
     How to define a custom model
 
     .. code-block:: python
@@ -1356,7 +1355,7 @@ def make_obs_var(
         """Create a `TensorVariable` for an observed random variable.
 
         Parameters
-        ==========
+        ----------
         rv_var
             The random variable that is observed.
             Its dimensionality must be compatible with the data already.
@@ -1808,7 +1807,7 @@ def point_logps(self, point=None, round_vals=2):
 
 
 class BlockModelAccess(Model):
-    """This class can be used to prevent user access to Model contexts"""
+    """Can be used to prevent user access to Model contexts"""
 
     def __init__(self, *args, error_msg_on_access="Model access is blocked", **kwargs):
         self.error_msg_on_access = error_msg_on_access
@@ -1829,7 +1828,6 @@ def set_data(new_data, model=None, *, coords=None):
 
     Examples
     --------
-
     This example shows how to change the shape of the likelihood to correspond automatically with
     `x`, the predictor in a regression model.
 

pymc/model_graph.py

@@ -199,6 +199,7 @@ def get_plates(self, var_names: Optional[Iterable[VarName]] = None) -> Dict[str,
 
         Just groups by the shape of the underlying distribution.  Will be wrong
         if there are two plates with the same shape.
+
         Returns
         -------
         dict

pymc/ode/__init__.py

@@ -1,5 +1,5 @@
 """
-This submodule contains tools used to perform inference on ordinary differential equations.
+Contains tools used to perform inference on ordinary differential equations.
 
 Due to the nature of the model (as well as included solvers), ODE solution may perform slowly.
 Another library based on PyMC--sunode--has implemented Adams' method and BDF (backward differentation formula) using the very fast SUNDIALS suite of ODE and PDE solvers.

pymc/ode/ode.py

@@ -42,7 +42,6 @@ class DifferentialEquation(Op):
 
     Parameters
     ----------
-
     func : callable
         Function specifying the differential equation. Must take arguments y (n_states,), t (scalar), p (n_theta,)
     times : array
@@ -57,7 +56,6 @@ class DifferentialEquation(Op):
 
     Examples
     --------
-
     .. code-block:: python
 
         def odefunc(y, t, p):
@@ -108,7 +106,7 @@ def __init__(self, func, times, *, n_states, n_theta, t0=0):
         self._output_sensitivities = {}
 
     def _system(self, Y, t, p):
-        r"""This is the function that will be passed to odeint. Solves both ODE and sensitivities.
+        r"""The function that will be passed to odeint. Solves both ODE and sensitivities.
 
         Parameters
         ----------

pymc/pytensorf.py

@@ -203,7 +203,7 @@ def walk_model(
     """Walk model graphs and yield their nodes.
 
     Parameters
-    ==========
+    ----------
     graphs
         The graphs to walk.
     stop_at_vars
@@ -235,12 +235,12 @@ def _replace_rvs_in_graphs(
     This will *not* recompute test values.
 
     Parameters
-    ==========
+    ----------
     graphs
         The graphs in which random variables are to be replaced.
 
     Returns
-    =======
+    -------
     Tuple containing the transformed graphs and a ``dict`` of the replacements
     that were made.
     """
@@ -296,7 +296,7 @@ def rvs_to_value_vars(
     This will *not* recompute test values in the resulting graphs.
 
     Parameters
-    ==========
+    ----------
     graphs
         The graphs in which to perform the replacements.
     apply_transforms