Merge pull request #532 from kinnala/impro-docs

Small improvements to the docs

docs/index.rst

@@ -26,8 +26,8 @@ Table of contents
 
    self
    overview
-   elements
    forms
    bcs
+   elements
    listofexamples
    api

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
 ======================

skfem/assembly/__init__.py

@@ -1,25 +1,32 @@
-# -*- 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`.
 
 >>> from skfem import *
 >>> 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 +39,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

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

skfem/mesh/__init__.py

@@ -1,33 +1,23 @@
-# -*- 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
 - :class:`~skfem.mesh.MeshTet`, tetrahedral mesh
 - :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`.
 
 """