Add pylint check for missing docstrings

.github/workflows/lint_optional.yml

@@ -0,0 +1,34 @@
+# Runs optional, "nice to have" formatting checks
+
+name: lint-optional
+
+# Controls when the action will run.
+on:
+    push:
+        branches:
+          - main
+    pull_request:
+
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job
+  lint-optional:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+
+      - name: Install Pylint
+        run: |
+          pip install pylint
+
+      - name: Pylint code analysis
+        run: |
+          pylint --disable=all --enable=missing-docstring scico

scico/__init__.py

@@ -1,3 +1,12 @@
+# Copyright (C) 2021 by SCICO Developers
+# All rights reserved. BSD 3-clause License.
+# This file is part of the SCICO package. Details of the copyright and
+# user license can be found in the 'LICENSE' file distributed with the
+# package.
+
+"""SCICO -- a Python package for solving the inverse problems that arise in scientific imaging applications."""
+
+
 __version__ = "0.0.1b1"
 
 import sys

scico/_autograd.py

@@ -1,3 +1,12 @@
+# Copyright (C) 2020-2021 by SCICO Developers
+# All rights reserved. BSD 3-clause License.
+# This file is part of the SCICO package. Details of the copyright and
+# user license can be found in the 'LICENSE' file distributed with the
+# package.
+
+"""Automatric differentiation tools."""
+
+
 from typing import Any, Callable, Sequence, Tuple, Union
 
 import jax

scico/_generic_operators.py

@@ -166,6 +166,7 @@ def __init__(
             self.jit()
 
     def jit(self):
+        """Activate just-in-time compilation for the `_eval` method."""
         self._eval = jax.jit(self._eval)
 
     def __call__(
@@ -276,9 +277,23 @@ def __truediv__(self, other):
         )
 
     def jvp(self, primals, tangents):
+        """Computes a Jacobian-vector product.
+
+        Args:
+            primals:  Values at which the Jacobian is evaluated.
+            tangents:  Vector in the Jacobian-vector product.
+        """
+
         return jax.jvp(self, primals, tangents)
 
-    def vjp(self, *primals, has_aux: bool = False):
+    def vjp(self, *primals):
+        """Computes a vector-Jacobian product.
+
+        Args:
+            primals:  Sequence of values at which the Jacobian is evaluated,
+               with length equal to the number of position arguments of `_eval`.
+        """
+
         primals, self_vjp = jax.vjp(self, *primals)
         return primals, self_vjp
 

scico/blockarray.py

@@ -765,19 +765,6 @@ def __init__(self, shapes, dtype):
         #: Array specifying boundaries of components as indices in base array
         self.bndpos: np.ndarray = np.r_[0, np.cumsum(sizes)]
 
-    @core.aval_property
-    def data(self):
-        return bk_data_p.bind(self)
-
-
-# Register BlockArray._data as a primitive
-bk_data_p = core.Primitive("bk_data")
-
-
-@bk_data_p.def_impl
-def _bk_data_impl(mat):
-    return mat._data
-
 
 # The Jax class is heavily inspired by SparseArray/AbstractSparseArray here:
 # https://github.com/google/jax/blob/7724322d1c08c13008815bfb52759a29c2a6823b/tests/custom_object_test.py

scico/linop/optics.py

@@ -78,6 +78,8 @@ def radial_transverse_frequency(
 
 
 class Propagator(LinearOperator):
+    """Base class for AngularSpectrum and Fresnel propagator."""
+
     def __init__(
         self,
         input_shape: Shape,
@@ -87,8 +89,7 @@ def __init__(
         pad_factor: int = 1,
         **kwargs,
     ):
-        r"""Base class for AngularSpectrum and Fresnel propagator
-
+        r"""
         Args:
             input_shape: Shape of input array.  Can be a tuple of length
                1 or 2.

scico/linop/radon_astra.py

@@ -147,6 +147,13 @@ def f(y):
         return hcb.call(f, y, result_shape=jax.ShapeDtypeStruct(self.input_shape, self.input_dtype))
 
     def fbp(self, sino: JaxArray, filter_type: str = "Ram-Lak") -> JaxArray:
+        """Perform tomographic reconstruction using the filtered back
+        projection (FBP) algorithm.
+
+        Args:
+            sino: Sinogram to reconstruct.
+            filter_type: Which filter to use, see `cfg.FilterType` in `<https://www.astra-toolbox.com/docs/algs/FBP_CUDA.html>`_.
+        """
 
         # Just use the CPU FBP alg for now; hitting memory issues with GPU one.
         def f(sino):

scico/numpy/__init__.py

@@ -118,6 +118,8 @@
 
 @wraps(jnp.vdot)
 def vdot(a, b):
+    """Dot product of `a` and `b` (with first argument complex conjugated).
+    Wrapped to work on `BlockArray`s."""
     if isinstance(a, BlockArray):
         a = a.ravel()
     if isinstance(b, BlockArray):

scico/numpy/linalg.py

@@ -70,8 +70,10 @@ def wrapper(*args, **kwargs):
 solve = _matrixop_linalg_wrapper(jla.solve)
 
 
-# multidot is somewhat uniq
+# multidot is somewhat unique
 def multi_dot(arrays, *, precision=None):
+    """Computes the dot product of two or more arrays.
+    Wrapped to work with `MatrixOperator`s."""
     arrays_ = [_extract_if_matrix(_) for _ in arrays]
     return jla.multi_dot(arrays_, precision=precision)