From bfeeca5825ec44813dbda59a58a37584709a8f42 Mon Sep 17 00:00:00 2001
From: Tom Gustafsson <tom.gustafsson@iki.fi>
Date: Sun, 27 Dec 2020 01:17:25 +0200
Subject: [PATCH 1/2] Small improvements to the docs

---
 docs/index.rst             |  2 +-
 docs/overview.rst          |  2 +-
 skfem/assembly/__init__.py | 30 ++++++++++--------------------
 skfem/element/__init__.py  |  6 ++++++
 skfem/mesh/__init__.py     | 26 ++++++++------------------
 5 files changed, 26 insertions(+), 40 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 56db367cd..2135a4bdc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -26,8 +26,8 @@ Table of contents
 
    self
    overview
-   elements
    forms
    bcs
+   elements
    listofexamples
    api
diff --git a/docs/overview.rst b/docs/overview.rst
index ef409dabb..dad731920 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -13,7 +13,7 @@ Module: skfem.mesh
 Module: skfem.element
 =====================
 
-See :mod:`skfem.element`.
+This module defines finite elements. See :mod:`skfem.element`.
 
 Module: skfem.assembly
 ======================
diff --git a/skfem/assembly/__init__.py b/skfem/assembly/__init__.py
index 69050269b..b4dc1c38e 100644
--- a/skfem/assembly/__init__.py
+++ b/skfem/assembly/__init__.py
@@ -1,6 +1,5 @@
-# -*- coding: utf-8 -*-
-r"""This module contains rest of the tools for performing the finite element
-assembly. The basic workflow of assembly is the following:
+r"""This module performs the finite element assembly. The basic workflow is the
+following:
 
 1. Initialize :class:`~skfem.mesh.Mesh` and :class:`~skfem.element.Element`.
 
@@ -8,18 +7,24 @@
 >>> m = MeshTri()
 >>> e = ElementTriP1()
 
-2. Create :class:`~skfem.assembly.InteriorBasis` and/or
+2. Create :class:`~skfem.assembly.InteriorBasis` or
    :class:`~skfem.assembly.FacetBasis` objects.
 
 >>> basis = InteriorBasis(m, e)
 
 3. Define the forms using :class:`~skfem.assembly.BilinearForm`,
-   :class:`~skfem.assembly.LinearForm`, and/or
+   :class:`~skfem.assembly.LinearForm`, or
    :class:`~skfem.assembly.Functional`.
 
 >>> form_a = BilinearForm(lambda u, v, w: u * v)
 >>> form_l = LinearForm(lambda v, w: w.x[0] ** 2 * v)
 
+Mathematically the above forms are
+
+.. math::
+
+    a(u,v) = \int_\Omega u v \,\mathrm{d}x \quad \mathrm{and} \quad l(v) = \int_\Omega x^2v \,\mathrm{d}x.
+
 4. Assemble using :func:`~skfem.assembly.asm`.
 
 >>> A = asm(form_a, basis)
@@ -32,21 +37,6 @@
 >>> b
 array([0.0162037 , 0.15046296, 0.06712963, 0.09953704])
 
-The above example assembles the matrix corresponding
-to the bilinear form
-
-.. math::
-
-    a(u,v) = \int_0^1 \int_0^1 u(x,y)v(x,y) \,\mathrm{d}x \,\mathrm{d}y
-
-and the vector corresponding to the linear form
-
-.. math::
-
-    l(v) = \int_0^1 \int_0^1 x^2v(x,y) \,\mathrm{d}x \,\mathrm{d}y
-
-using piecewise-linear basis functions.
-
 """
 
 from typing import Union
diff --git a/skfem/element/__init__.py b/skfem/element/__init__.py
index b644574cf..4de3dff42 100644
--- a/skfem/element/__init__.py
+++ b/skfem/element/__init__.py
@@ -6,6 +6,9 @@
 :class:`~skfem.assembly.FacetBasis`.  See below for a list of supported
 elements.
 
+Choosing a finite element
+-------------------------
+
 Here are some general instructions for choosing an :class:`Element` class.
 Firstly, the naming of the element classes reflects their compatibility with
 the mesh types:
@@ -38,6 +41,9 @@
 should be enforced strongly or weakly.  See :ref:`finddofs` for more
 information.
 
+List of elements
+----------------
+
 """
 
 from .discrete_field import DiscreteField
diff --git a/skfem/mesh/__init__.py b/skfem/mesh/__init__.py
index 68152a9f2..53a8dd0ad 100644
--- a/skfem/mesh/__init__.py
+++ b/skfem/mesh/__init__.py
@@ -1,8 +1,6 @@
-# -*- coding: utf-8 -*-
-"""This module defines different types of finite element meshes.  Meshes can
-be created using various built-in constructors or loaded from external
-formats using `meshio <https://github.com/nschloe/meshio>`_.  The supported
-types are
+"""This module defines finite element meshes.  Meshes can be created using
+built-in constructors or loaded from external formats using `meshio
+<https://github.com/nschloe/meshio>`_.  The supported types are
 
 - :class:`~skfem.mesh.MeshTri`, triangular mesh
 - :class:`~skfem.mesh.MeshQuad`, quadrilateral mesh
@@ -10,24 +8,16 @@
 - :class:`~skfem.mesh.MeshHex`, hexahedral mesh
 - :class:`~skfem.mesh.MeshLine`, one-dimensional mesh
 
-For example, initializing the default mesh in the unit square can be done as
-follows:
+Default constructor creates a mesh for the unit square:
 
 >>> from skfem.mesh import MeshTri
 >>> MeshTri()
 Triangular mesh with 4 vertices and 2 elements.
 
-Each mesh type has several constructors, e.g.,
-
->>> MeshTri.init_lshaped()
-Triangular mesh with 8 vertices and 6 elements.
->>> MeshTri.init_tensor([0.0, 1.0], [0.0, 1.0, 2.0])
-Triangular mesh with 6 vertices and 4 elements.
-
-A list of constructors can be found in the class docstring.
-
-Importing from external formats can be done with the constructor
-:meth:`~skfem.mesh.Mesh.load`.
+Each mesh type has several constructors; see the docstring, e.g.,
+``help(MeshTri)`` or click :class:`~skfem.mesh.MeshTri` in the online
+documentation.  Importing from external formats can be done with the
+constructor :meth:`~skfem.mesh.Mesh.load`.
 
 """
 

From 928726824d09935c6e649d73b47fef63ae53a783 Mon Sep 17 00:00:00 2001
From: Tom Gustafsson <tom.gustafsson@iki.fi>
Date: Sun, 27 Dec 2020 01:30:18 +0200
Subject: [PATCH 2/2] Fix flake8

---
 skfem/assembly/__init__.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/skfem/assembly/__init__.py b/skfem/assembly/__init__.py
index b4dc1c38e..219e90a25 100644
--- a/skfem/assembly/__init__.py
+++ b/skfem/assembly/__init__.py
@@ -23,7 +23,9 @@
 
 .. math::
 
-    a(u,v) = \int_\Omega u v \,\mathrm{d}x \quad \mathrm{and} \quad l(v) = \int_\Omega x^2v \,\mathrm{d}x.
+    a(u,v) = \int_\Omega u v \,\mathrm{d}x
+    \quad \mathrm{and} \quad
+    l(v) = \int_\Omega x^2v \,\mathrm{d}x.
 
 4. Assemble using :func:`~skfem.assembly.asm`.