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

Author: michaelosthege

.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