Add module docstrings

examples/__init__.py

@@ -0,0 +1,3 @@
+"""Demonstration scripts and high-level tests of the :mod:`fipy` package
+"""
+__docformat__ = 'restructuredtext'

fipy/__init__.py

@@ -1,6 +1,6 @@
-"""
-:term:`FiPy` is an object oriented, partial differential equation (PDE) solver,
-written in :term:`Python`, based on a standard finite volume (FV) approach. The
+"""An object oriented, partial differential equation (PDE) solver
+
+:term:`FiPy` is based on a standard finite volume (FV) approach. The
 framework has been developed in the Materials Science and Engineering Division
 (MSED_) and Center for Theoretical and Computational Materials Science (CTCMS_),
 in the Material Measurement Laboratory (MML_) at the National Institute of

fipy/boundaryConditions/__init__.py

@@ -1,4 +1,8 @@
+"""Boundary conditions
+"""
 from __future__ import unicode_literals
+__docformat__ = 'restructuredtext'
+
 from fipy.boundaryConditions.constraint import *
 from fipy.boundaryConditions.fixedFlux import *
 from fipy.boundaryConditions.fixedValue import *

fipy/boundaryConditions/boundaryCondition.py

@@ -1,3 +1,5 @@
+"""Boundary condition base class
+"""
 from __future__ import unicode_literals
 from builtins import object
 __docformat__ = 'restructuredtext'
@@ -11,8 +13,7 @@
 __all__ = [text_to_native_str(n) for n in __all__]
 
 class BoundaryCondition(object):
-    """
-    Generic boundary condition base class.
+    """Generic boundary condition base class.
 
     .. attention:: This class is abstract. Always create one of its subclasses.
     """

fipy/boundaryConditions/constraint.py

@@ -1,3 +1,5 @@
+"""Restriction on value of a :class:`~fipy.variables.variable.Variable`
+"""
 from __future__ import unicode_literals
 from builtins import object
 __docformat__ = 'restructuredtext'
@@ -7,7 +9,7 @@
 __all__ = [text_to_native_str(n) for n in __all__]
 
 class Constraint(object):
-    """Object to hold a `Variable` to `value` at `where`
+    """Holds a :class:`~fipy.variables.variable.Variable` to `value` at `where`
 
     see :meth:`~fipy.variables.variable.Variable.constrain`
     """

fipy/boundaryConditions/fixedFlux.py

@@ -1,3 +1,5 @@
+"""Boundary condition of order 1
+"""
 from __future__ import unicode_literals
 __docformat__ = 'restructuredtext'
 
@@ -12,10 +14,15 @@
 __all__ = [text_to_native_str(n) for n in __all__]
 
 class FixedFlux(BoundaryCondition):
-    r"""
+    r"""Adds a Neumann contribution to the system of equations.
 
-    The `FixedFlux` boundary condition adds a contribution, equivalent to a
-    fixed flux (Neumann condition), to the equation's RHS vector.  The
+    Implements
+
+    .. math::
+
+       \hat{n}\cdot\vec{J}|_\text{faces} = \text{value}
+
+    The
     contribution, given by `value`, is only added to entries corresponding to
     the specified `faces`, and is weighted by the face areas.
 

fipy/boundaryConditions/fixedValue.py

@@ -1,3 +1,5 @@
+"""Boundary condition of order 0
+"""
 from __future__ import unicode_literals
 __docformat__ = 'restructuredtext'
 
@@ -17,10 +19,15 @@
 __all__ = [text_to_native_str(n) for n in __all__]
 
 class FixedValue(BoundaryCondition):
-    r"""
-    The `FixedValue` boundary condition adds a contribution, equivalent to a
-    fixed value (Dirichlet condition), to the equation's RHS vector and
-    coefficient matrix. The contributions are given by
+    r"""Adds a Dirichlet contribution to the system of equations.
+
+    Implements
+
+    .. math::
+
+       \phi|_\text{faces} = \text{value}
+
+    The contributions are given by
     :math:`-\mathtt{value}\times G_{\text{face}}`
     for the RHS vector and :math:`G_{\text{face}}` for
     the coefficient matrix. The parameter :math:`G_{\text{face}}` represents the

fipy/boundaryConditions/nthOrderBoundaryCondition.py

@@ -1,3 +1,5 @@
+"""Boundary condition of specified derivative order
+"""
 from __future__ import unicode_literals
 __docformat__ = 'restructuredtext'
 
@@ -12,13 +14,18 @@
 __all__ = [text_to_native_str(n) for n in __all__]
 
 class NthOrderBoundaryCondition(BoundaryCondition):
-    """
+    r"""Adds an appropriate contribution to the system of equations
+
+    Implements
+
+    .. math::
+
+       \hat{n}\cdot\nabla^\text{order} \phi |_\text{faces} = \text{value}
 
     This boundary condition is generally used in conjunction with a
     `ImplicitDiffusionTerm` that has multiple coefficients.  It does not
     have any direct effect on the solution matrices, but its derivatives
     do.
-
     """
 
     def __init__(self, faces, value, order):

fipy/boundaryConditions/test.py

@@ -1,4 +1,4 @@
-"""Test numeric implementation of the mesh
+"""Test boundary conditions
 """
 from __future__ import unicode_literals
 

fipy/matrices/__init__.py

@@ -0,0 +1,3 @@
+"""Sparse matrices
+"""
+__docformat__ = 'restructuredtext'

fipy/meshes/__init__.py

@@ -1,4 +1,8 @@
+"""Domain geometry and topology
+"""
 from __future__ import unicode_literals
+__docformat__ = 'restructuredtext'
+
 from fipy.meshes.factoryMeshes import *
 from fipy.meshes.periodicGrid1D import *
 from fipy.meshes.periodicGrid2D import *

fipy/solvers/__init__.py

@@ -1,4 +1,8 @@
+"""Solving sparse linear systems
+"""
 from __future__ import unicode_literals
+__docformat__ = 'restructuredtext'
+
 from builtins import str
 
 import logging

fipy/steppers/__init__.py

@@ -1,3 +1,8 @@
+"""(Obsolete) utilities for iterating time steps
+
+Use `steppyngstounes <https://pages.nist.gov/steppyngstounes/en/latest>`_
+instead.
+"""
 from __future__ import division
 from __future__ import unicode_literals
 __docformat__ = 'restructuredtext'

fipy/terms/__init__.py

@@ -1,4 +1,8 @@
+""":ref:`Discretizations <section:discretization>` of partial differential equation expressions
+"""
 from __future__ import unicode_literals
+__docformat__ = 'restructuredtext'
+
 class ExplicitVariableError(Exception):
     def __init__(self, s='Terms with explicit Variables cannot mix with Terms with implicit Variables.'):
         Exception.__init__(self, s)