Format docstrings automatically (#580)

docs/source/create_performance_plots.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
-"""
-Code for creating performance plots
+"""Code for creating performance plots.
 
 .. codeauthor:: David Zwicker <[email protected]>
 """
@@ -32,7 +31,7 @@
 
 
 def time_function(func, arg, repeat=3, use_out=False):
-    """estimates the computation speed of a function
+    """Estimates the computation speed of a function.
 
     Args:
         func (callable): The function to test
@@ -54,7 +53,7 @@ def time_function(func, arg, repeat=3, use_out=False):
 
 
 def get_performance_data(periodic=False):
-    """obtain the data used in the performance plot
+    """Obtain the data used in the performance plot.
 
     Args:
         periodic (bool): The boundary conditions of the underlying grid
@@ -90,7 +89,7 @@ def get_performance_data(periodic=False):
 
 
 def plot_performance(performance_data, title=None):
-    """plot the performance data
+    """Plot the performance data.
 
     Args:
         performance_data: The data obtained from calling
@@ -129,7 +128,7 @@ def plot_performance(performance_data, title=None):
 
 
 def main():
-    """run main scripts"""
+    """Run main scripts."""
     data = get_performance_data(periodic=False)
     plot_performance(data, title="2D Laplacian (reflecting BCs)")
     plt.savefig("performance_noflux.pdf", transparent=True)

docs/source/parse_examples.py

@@ -11,7 +11,7 @@
 
 
 def main():
-    """parse all examples and write them in a special example module"""
+    """Parse all examples and write them in a special example module."""
     # create the output directory
     OUTPUT.mkdir(parents=True, exist_ok=True)
 

docs/source/run_autodoc.py

@@ -16,8 +16,8 @@
 
 
 def replace_in_file(infile, replacements, outfile=None):
-    """reads in a file, replaces the given data using python formatting and
-    writes back the result to a file.
+    """Reads in a file, replaces the given data using python formatting and writes back
+    the result to a file.
 
     Args:
         infile (str):
@@ -27,7 +27,6 @@ def replace_in_file(infile, replacements, outfile=None):
         outfile (str):
             Output file to which the data is written. If it is omitted, the
             input file will be overwritten instead
-
     """
     if outfile is None:
         outfile = infile

docs/sphinx_ext/package_config.py

@@ -3,7 +3,7 @@
 
 
 class PackageConfigDirective(SphinxDirective):
-    """directive that displays all package configuration items"""
+    """Directive that displays all package configuration items."""
 
     has_content = True
     required_arguments = 0

docs/sphinx_ext/simplify_typehints.py

@@ -1,6 +1,4 @@
-"""
-Simple sphinx plug-in that simplifies  type information in function signatures
-"""
+"""Simple sphinx plug-in that simplifies  type information in function signatures."""
 
 import re
 
@@ -56,10 +54,10 @@
 def process_signature(
     app, what: str, name: str, obj, options, signature, return_annotation
 ):
-    """Process signature by applying replacement rules"""
+    """Process signature by applying replacement rules."""
 
     def process(sig_obj):
-        """process the signature object"""
+        """Process the signature object."""
         if sig_obj is not None:
             for key, value in REPLACEMENTS_REGEX.items():
                 sig_obj = re.sub(key, value, sig_obj)
@@ -74,14 +72,14 @@ def process(sig_obj):
 
 
 def process_docstring(app, what: str, name: str, obj, options, lines):
-    """Process docstring by applying replacement rules"""
+    """Process docstring by applying replacement rules."""
     for i, line in enumerate(lines):
         for key, value in REPLACEMENTS:
             line = line.replace(key, value)
         lines[i] = line
 
 
 def setup(app):
-    """set up hooks for this sphinx plugin"""
+    """Set up hooks for this sphinx plugin."""
     app.connect("autodoc-process-signature", process_signature)
     app.connect("autodoc-process-docstring", process_docstring)

docs/sphinx_ext/toctree_filter.py

@@ -4,7 +4,7 @@
 
 
 class TocTreeFilter(TocTree):
-    """directive to filter table-of-contents entries"""
+    """Directive to filter table-of-contents entries."""
 
     hasPat = re.compile(r"^\s*:(.+):(.+)$")
 

examples/heterogeneous_bcs.py

@@ -28,7 +28,7 @@
 
 # define the boundary conditions, which here are calculated from a function
 def bc_value(adjacent_value, dx, x, y, t):
-    """return boundary value"""
+    """Return boundary value."""
     return np.sign(x)
 
 

examples/pde_1d_class.py

@@ -18,10 +18,10 @@
 
 
 class KortewegDeVriesPDE(PDEBase):
-    """Korteweg-de Vries equation"""
+    """Korteweg-de Vries equation."""
 
     def evolution_rate(self, state, t=0):
-        """implement the python version of the evolution equation"""
+        """Implement the python version of the evolution equation."""
         assert state.grid.dim == 1  # ensure the state is one-dimensional
         grad_x = state.gradient("auto_periodic_neumann")[0]
         return 6 * state * grad_x - grad_x.laplace("auto_periodic_neumann")

examples/pde_brusselator_class.py

@@ -25,7 +25,7 @@
 
 
 class BrusselatorPDE(PDEBase):
-    """Brusselator with diffusive mobility"""
+    """Brusselator with diffusive mobility."""
 
     def __init__(self, a=1, b=3, diffusivity=[1, 0.1], bc="auto_periodic_neumann"):
         super().__init__()
@@ -35,13 +35,13 @@ def __init__(self, a=1, b=3, diffusivity=[1, 0.1], bc="auto_periodic_neumann"):
         self.bc = bc  # boundary condition
 
     def get_initial_state(self, grid):
-        """prepare a useful initial state"""
+        """Prepare a useful initial state."""
         u = ScalarField(grid, self.a, label="Field $u$")
         v = self.b / self.a + 0.1 * ScalarField.random_normal(grid, label="Field $v$")
         return FieldCollection([u, v])
 
     def evolution_rate(self, state, t=0):
-        """pure python implementation of the PDE"""
+        """Pure python implementation of the PDE."""
         u, v = state
         rhs = state.copy()
         d0, d1 = self.diffusivity
@@ -50,7 +50,7 @@ def evolution_rate(self, state, t=0):
         return rhs
 
     def _make_pde_rhs_numba(self, state):
-        """nunmba-compiled implementation of the PDE"""
+        """Nunmba-compiled implementation of the PDE."""
         d0, d1 = self.diffusivity
         a, b = self.a, self.b
         laplace = state.grid.make_operator("laplace", bc=self.bc)

examples/pde_coupled.py

@@ -20,7 +20,7 @@
 
 
 class FitzhughNagumoPDE(PDEBase):
-    """FitzHugh–Nagumo model with diffusive coupling"""
+    """FitzHugh–Nagumo model with diffusive coupling."""
 
     def __init__(self, stimulus=0.5, τ=10, a=0, b=0, bc="auto_periodic_neumann"):
         super().__init__()

examples/pde_custom_class.py

@@ -15,10 +15,10 @@
 
 
 class KuramotoSivashinskyPDE(PDEBase):
-    """Implementation of the normalized Kuramoto–Sivashinsky equation"""
+    """Implementation of the normalized Kuramoto–Sivashinsky equation."""
 
     def evolution_rate(self, state, t=0):
-        """implement the python version of the evolution equation"""
+        """Implement the python version of the evolution equation."""
         state_lap = state.laplace(bc="auto_periodic_neumann")
         state_lap2 = state_lap.laplace(bc="auto_periodic_neumann")
         state_grad = state.gradient(bc="auto_periodic_neumann")

examples/pde_custom_numba.py

@@ -17,21 +17,21 @@
 
 
 class KuramotoSivashinskyPDE(PDEBase):
-    """Implementation of the normalized Kuramoto–Sivashinsky equation"""
+    """Implementation of the normalized Kuramoto–Sivashinsky equation."""
 
     def __init__(self, bc="auto_periodic_neumann"):
         super().__init__()
         self.bc = bc
 
     def evolution_rate(self, state, t=0):
-        """implement the python version of the evolution equation"""
+        """Implement the python version of the evolution equation."""
         state_lap = state.laplace(bc=self.bc)
         state_lap2 = state_lap.laplace(bc=self.bc)
         state_grad_sq = state.gradient_squared(bc=self.bc)
         return -state_grad_sq / 2 - state_lap - state_lap2
 
     def _make_pde_rhs_numba(self, state):
-        """nunmba-compiled implementation of the PDE"""
+        """Nunmba-compiled implementation of the PDE."""
         gradient_squared = state.grid.make_operator("gradient_squared", bc=self.bc)
         laplace = state.grid.make_operator("laplace", bc=self.bc)
 

examples/pde_sir.py

@@ -21,7 +21,7 @@
 
 
 class SIRPDE(PDEBase):
-    """SIR-model with diffusive mobility"""
+    """SIR-model with diffusive mobility."""
 
     def __init__(
         self, beta=0.3, gamma=0.9, diffusivity=0.1, bc="auto_periodic_neumann"
@@ -33,7 +33,7 @@ def __init__(
         self.bc = bc  # boundary condition
 
     def get_state(self, s, i):
-        """generate a suitable initial state"""
+        """Generate a suitable initial state."""
         norm = (s + i).data.max()  # maximal density
         if norm > 1:
             s /= norm

examples/py_modelrunner.py

@@ -21,7 +21,7 @@
 
 
 def run(storage, diffusivity=0.1):
-    """function that runs the model
+    """Function that runs the model.
 
     Args:
         storage (:mod:`~modelrunner.storage.group.StorageGroup`):

pde/__init__.py

@@ -1,7 +1,5 @@
-"""
-The py-pde package provides classes and methods for solving partial differential
-equations.
-"""
+"""The py-pde package provides classes and methods for solving partial differential
+equations."""
 
 # determine the package version
 try:

pde/fields/__init__.py

@@ -1,5 +1,4 @@
-"""
-Defines fields, which contain the actual data stored on a discrete grid.
+"""Defines fields, which contain the actual data stored on a discrete grid.
 
 .. autosummary::
    :nosignatures: