Add missing docstrings, remove pydocstyle skips (#667)

* docs in codegeneration

* docstrings

* docstyle

* flake

* docs in demos

* doc

Author: mscroggs

demo/BiharmonicHHJ.py

@@ -1,8 +1,10 @@
 # Copyright (C) 2016 Lizao Li
-#
-# The bilinear form a(u, v) and linear form L(v) for
-# Biharmonic equation in Hellan-Herrmann-Johnson (HHJ)
-# formulation.
+"""Biharmonis HHJ demo.
+
+The bilinear form a(u, v) and linear form L(v) for Biharmonic equation
+in Hellan-Herrmann-Johnson (HHJ) formulation.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, FacetNormal, FunctionSpace, Mesh, TestFunctions,
                  TrialFunctions, dot, dS, ds, dx, grad, inner, jump)
@@ -20,6 +22,7 @@
 
 
 def b(sigma, v):
+    """The form b."""
     n = FacetNormal(domain)
     return inner(sigma, grad(grad(v))) * dx \
         - dot(dot(sigma('+'), n('+')), n('+')) * jump(grad(v), n) * dS \

demo/BiharmonicRegge.py

@@ -1,7 +1,8 @@
 # Copyright (C) 2016 Lizao Li
-#
-# The bilinear form a(u, v) and linear form L(v) for
-# Biharmonic equation in Regge formulation.
+"""Biharmonic Regge demo.
+
+The bilinear form a(u, v) and linear form L(v) for Biharmonic equation in Regge formulation.
+"""
 import basix.ufl
 from ufl import (Coefficient, FacetNormal, FunctionSpace, Identity, Mesh,
                  TestFunctions, TrialFunctions, dot, dS, ds, dx, grad, inner,
@@ -20,10 +21,12 @@
 
 
 def S(mu):
+    """The form S."""
     return mu - Identity(3) * tr(mu)
 
 
 def b(mu, v):
+    """The form b."""
     n = FacetNormal(domain)
     return inner(S(mu), grad(grad(v))) * dx \
         - dot(dot(S(mu('+')), n('+')), n('+')) * jump(grad(v), n) * dS \

demo/CellGeometry.py

@@ -1,6 +1,9 @@
 # Copyright (C) 2013 Martin S. Alnaes
-#
-# A functional M involving a bunch of cell geometry quantities.
+"""Cell geometry demo.
+
+A functional M involving a bunch of cell geometry quantities.
+"""
+
 import basix.ufl
 from ufl import (CellVolume, Circumradius, Coefficient, FacetArea, FacetNormal,
                  FunctionSpace, Mesh, SpatialCoordinate, TrialFunction, ds, dx)

demo/ComplexPoisson.py

@@ -14,9 +14,12 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# The bilinear form a(u, v) and linear form L(v) for
-# Poisson's equation using bilinear elements on bilinear mesh geometry.
+"""Complex Poisson demo.
+
+The bilinear form a(u, v) and linear form L(v) for
+Poisson's equation using bilinear elements on bilinear mesh geometry.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, FunctionSpace, Mesh, TestFunction, TrialFunction,
                  dx, grad, inner)

demo/Components.py

@@ -14,8 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# This example demonstrates how to create vectors component-wise
+"""Components demo.
+
+This example demonstrates how to create vectors component-wise.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, FunctionSpace, Mesh, TestFunction, as_vector, dx,
                  inner)

demo/Conditional.py

@@ -14,8 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# Illustration on how to use Conditional to define a source term
+"""Conditional demo.
+
+Illustration on how to use Conditional to define a source term.
+"""
+
 import basix.ufl
 from ufl import (And, Constant, FunctionSpace, Mesh, Not, Or,
                  SpatialCoordinate, TestFunction, conditional, dx, ge, gt,

demo/ExpressionInterpolation.py

@@ -14,9 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFC. If not, see <http://www.gnu.org/licenses/>.
-#
-# Defines an Expression which evaluates the several different functions at
-# a set of interpolation points
+"""Expression interpolation demo.
+
+Defines an Expression which evaluates the several different functions at
+a set of interpolation points.
+"""
 
 import basix
 import basix.ufl

demo/FacetIntegrals.py

@@ -14,11 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# First added:  2009-03-20
-# Last changed: 2011-03-08
-#
-# Simple example of a form defined over exterior and interior facets.
+"""Facet integrals demo.
+
+Simple example of a form defined over exterior and interior facets.
+"""
+
 import basix.ufl
 from ufl import (FacetNormal, FunctionSpace, Mesh, TestFunction, TrialFunction,
                  avg, ds, dS, grad, inner, jump)

demo/FacetRestrictionAD.py

@@ -14,9 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
+"""Facet restriction demo."""
+
 import basix.ufl
 from ufl import (Coefficient, FunctionSpace, Mesh, TestFunction, TrialFunction,
-                 avg, derivative, dot, dS, dx, grad, inner)
+                 avg, derivative, dS, dx, grad, inner)
 
 element = basix.ufl.element("Discontinuous Lagrange", "triangle", 1)
 domain = Mesh(basix.ufl.element("Lagrange", "triangle", 1, shape=(2, )))

demo/HyperElasticity.py

@@ -1,13 +1,12 @@
-#
 # Author: Martin Sandve Alnes
 # Date: 2008-12-22
-#
+# Modified by Garth N. Wells, 2009
+"""Hyper-elasticity demo."""
 
 import basix.ufl
-# Modified by Garth N. Wells, 2009
 from ufl import (Coefficient, Constant, FacetNormal, FunctionSpace, Identity,
                  Mesh, SpatialCoordinate, TestFunction, TrialFunction,
-                 derivative, det, diff, dot, ds, dx, exp, grad, inner, inv,
+                 derivative, det, diff, ds, dx, exp, grad, inner, inv,
                  tetrahedron, tr, variable)
 
 # Cell and its properties

demo/MassAction.py

@@ -3,8 +3,7 @@
 # This file is part of FFCx. (https://www.fenicsproject.org)
 #
 # SPDX-License-Identifier:    LGPL-3.0-or-later
-
-import numpy as np
+"""Mass action demo."""
 
 import basix
 import ufl

demo/MassDG0.py

@@ -14,8 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# The bilinear form for a mass matrix.
+"""DG mass matrix demo.
+
+The bilinear form for a mass matrix.
+"""
+
 import basix.ufl
 from ufl import FunctionSpace, Mesh, TestFunction, TrialFunction, dx, inner
 

demo/MassHcurl_2D_1.py

@@ -14,6 +14,7 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
+"""H(curl) mass matrix demo."""
 import basix.ufl
 from ufl import FunctionSpace, Mesh, TestFunction, TrialFunction, dx, inner
 

demo/MassHdiv_2D_1.py

@@ -14,6 +14,8 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
+"""H(div) mass matrix demo."""
+
 import basix.ufl
 from ufl import FunctionSpace, Mesh, TestFunction, TrialFunction, dx, inner
 

demo/MathFunctions.py

@@ -14,8 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# Test all algebra operators on Coefficients.
+"""Math function demo.
+
+Test all algebra operators on Coefficients.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, FunctionSpace, Mesh, acos, asin, atan, bessel_J,
                  bessel_Y, cos, dx, erf, exp, ln, sin, sqrt, tan)

demo/MetaData.py

@@ -14,8 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# Test form for metadata.
+"""Metadata demo.
+
+Test form for metadata.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, Constant, FunctionSpace, Mesh, TestFunction,
                  TrialFunction, dx, grad, inner)

demo/Mini.py

@@ -14,11 +14,14 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# Illustration of vector sum of elements (EnrichedElement): The
-# bilinear form a(u, v) for the Stokes equations using a mixed
-# formulation involving the Mini element. The velocity element is
-# composed of a P1 element augmented by the cubic bubble function.
+"""Mini element demo.
+
+Illustration of vector sum of elements (EnrichedElement): The
+bilinear form a(u, v) for the Stokes equations using a mixed
+formulation involving the Mini element. The velocity element is
+composed of a P1 element augmented by the cubic bubble function.
+"""
+
 import basix.ufl
 from ufl import (FunctionSpace, Mesh, TestFunctions, TrialFunctions, div, dx,
                  grad, inner)

demo/MixedCoefficient.py

@@ -16,8 +16,8 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# Mixed coefficient.
+"""Mixed coefficient demo."""
+
 import basix.ufl
 from ufl import Coefficients, FunctionSpace, Mesh, dot, dS, dx
 

demo/MixedGradient.py

@@ -1,3 +1,5 @@
+"""Mixed gradient demo."""
+
 import basix.ufl
 from ufl import (FunctionSpace, Mesh, TestFunctions, TrialFunctions, ds, grad,
                  inner)

demo/MixedPoissonDual.py

@@ -14,12 +14,12 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with DOLFINx. If not, see <http://www.gnu.org/licenses/>.
-#
-# First added:  2014-01-29
-# Last changed: 2014-01-29
-#
-# The bilinear form a(u, v) and linear form L(v) for a two-field
-# (mixed) formulation of Poisson's equation
+"""Mixed Poisson dual demo.
+
+The bilinear form a(u, v) and linear form L(v) for a two-field
+(mixed) formulation of Poisson's equation.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, FunctionSpace, Mesh, TestFunctions,
                  TrialFunctions, ds, dx, grad, inner)

demo/Normals.py

@@ -14,9 +14,12 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# This example demonstrates how to use the facet normals
-# Merely project the normal onto a vector section.
+"""Normals demo.
+
+This example demonstrates how to use the facet normals
+Merely project the normal onto a vector section.
+"""
+
 import basix.ufl
 from ufl import (FacetNormal, FunctionSpace, Mesh, TestFunction, TrialFunction,
                  ds, inner, triangle)

demo/Poisson1D.py

@@ -14,9 +14,11 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# The bilinear form a(u, v) and linear form L(v) for
-# Poisson's equation.
+"""1D Poisson demo.
+
+The bilinear form a(u, v) and linear form L(v) for Poisson's equation.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, FunctionSpace, Mesh, TestFunction, TrialFunction,
                  dx, grad, inner)

demo/PoissonQuad.py

@@ -14,9 +14,12 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# The bilinear form a(u, v) and linear form L(v) for
-# Poisson's equation using bilinear elements on bilinear mesh geometry.
+"""Quadrilateral Poisson demo.
+
+The bilinear form a(u, v) and linear form L(v) for
+Poisson's equation using bilinear elements on bilinear mesh geometry.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, FunctionSpace, Mesh, TestFunction, TrialFunction,
                  dx, grad, inner)

demo/ProjectionManifold.py

@@ -14,9 +14,12 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# This demo illustrates use of finite element spaces defined over
-# simplicies embedded in higher dimensions
+"""Projection manifold demo.
+
+This demo illustrates use of finite element spaces defined over
+simplicies embedded in higher dimensions.
+"""
+
 import basix.ufl
 from ufl import (FunctionSpace, Mesh, TestFunctions, TrialFunctions, div, dx,
                  inner)

demo/ReactionDiffusion.py

@@ -14,9 +14,12 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# The bilinear form a(u, v) and linear form L(v) for a simple
-# reaction-diffusion equation using simplified tuple notation.
+"""Reaction-diffusion demo.
+
+The bilinear form a(u, v) and linear form L(v) for a simple
+reaction-diffusion equation using simplified tuple notation.
+"""
+
 import basix.ufl
 from ufl import (Coefficient, FunctionSpace, Mesh, TestFunction, TrialFunction,
                  dx, grad, inner)

demo/SpatialCoordinates.py

@@ -14,10 +14,12 @@
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with FFCx. If not, see <http://www.gnu.org/licenses/>.
-#
-# The bilinear form a(u, v) and linear form L(v) for
-# Poisson's equation where spatial coordinates are used to define the source
-# and boundary flux terms.
+"""Spatial coordinates demo.
+
+The bilinear form a(u, v) and linear form L(v) for Poisson's equation where
+spatial coordinates are used to define the source and boundary flux terms.
+"""
+
 import basix.ufl
 from ufl import (FunctionSpace, Mesh, SpatialCoordinate, TestFunction,
                  TrialFunction, ds, dx, exp, grad, inner, sin)