Use Literate.jl to generate automatically documentation

Documentation can be automatically generated from test files using
Literate.jl. Looks promising approach!

.gitignore

@@ -1,5 +1,6 @@
 docs/build/
 docs/site/
+docs/src/tests
 *.cov
 *.pyc
 *.swp

docs/make.jl

@@ -1,11 +1,28 @@
 # This file is a part of JuliaFEM.
 # License is MIT: see https://github.com/JuliaFEM/HeatTransfer.jl/blob/master/LICENSE
 
-using Documenter, HeatTransfer
+haskey(Pkg.installed(), "Literate") || Pkg.add("Literate")
+
+using Documenter, HeatTransfer, Literate
+
+# automatically generate documentation from tests
+pkg_dir = Pkg.dir("HeatTransfer")
+testdir = joinpath(pkg_dir, "test")
+outdir = joinpath(pkg_dir, "docs", "src", "tests")
+test_pages = []
+for test_file in readdir(joinpath(pkg_dir, "test"))
+    startswith(test_file, "test_") || continue
+    Literate.markdown(joinpath(testdir, test_file), outdir; documenter=true)
+    generated_test_file = joinpath("tests", first(splitext(test_file)) * ".md")
+    push!(test_pages, generated_test_file)
+end
 
 makedocs(modules=[HeatTransfer],
          format = :html,
          checkdocs = :all,
          sitename = "HeatTransfer.jl",
-         pages = ["index.md"]
+         pages = [
+                  "index.md",
+                  "Examples" => test_pages
+                 ]
         )

test/test_heat_exchange_bc.jl

@@ -1,10 +1,22 @@
 # This file is a part of JuliaFEM.
 # License is MIT: see https://github.com/JuliaFEM/HeatTransfer.jl/blob/master/LICENSE
 
+#' # Use of heat exchange boundary condition
+#'
+#' Boundary conditions needs fields `heat transfer coefficient` and
+#' `external temperature` defined. Boundary condition is of type
+#' ```math
+#' f = h\left(T-T_{\mathrm{u}}\right)
+#' ```
+
 using HeatTransfer
 using FEMBase
 using FEMBase.Test
 
+#' Set up initial data
+
+tic()
+
 X = Dict(
     1 => [0.0,0.0],
     2 => [1.0,0.0])
@@ -13,15 +25,27 @@ T = Dict(
     1 => 0.0,
     2 => 0.0)
 
+#' Create element and update fields
+
 element = Element(Seg2, [1, 2])
 update!(element, "geometry", X)
 update!(element, "temperature", 0.0 => T)
 update!(element, "heat transfer coefficient", 6.0)
 update!(element, "external temperature", 1.0)
+
+#' Create problem, add elements to problem and assemble at time ``t=0``:
+
 problem = Problem(PlaneHeat, "test problem", 1)
 add_elements!(problem, [element])
 assemble!(problem, 0.0)
+
+#' Test for stiffness matrix ``\boldsymbol{K}`` and force vector ``\boldsymbol{f}``:
+
 K = full(problem.assembly.K)
 f = full(problem.assembly.f)
 @test isapprox(K, [2.0 1.0; 1.0 2.0])
 @test isapprox(f, [3.0; 3.0])
+
+#' Script execution time:
+
+toc();

test/test_heat_flux_bc_2d.jl

@@ -1,6 +1,8 @@
 # This file is a part of JuliaFEM.
 # License is MIT: see https://github.com/JuliaFEM/HeatTransfer.jl/blob/master/LICENSE
 
+#' # Use of flux boundary condition in 2d heat problem
+
 using HeatTransfer
 using FEMBase
 using FEMBase.Test

test/test_heat_flux_bc_3d.jl

@@ -1,6 +1,8 @@
 # This file is a part of JuliaFEM.
 # License is MIT: see https://github.com/JuliaFEM/HeatTransfer.jl/blob/master/LICENSE
 
+#' # Use of flux boundary condition in 3d heat problem
+
 using HeatTransfer
 using FEMBase
 using FEMBase.Test

test/test_stiffness_matrix_and_heat_source_2d.jl

@@ -1,6 +1,12 @@
 # This file is a part of JuliaFEM.
 # License is MIT: see https://github.com/JuliaFEM/HeatTransfer.jl/blob/master/LICENSE
 
+#' # Assembling stiffness matrix and force vector for 2d heat problem
+
+using HeatTransfer
+using FEMBase
+using FEMBase.Test
+
 X = Dict(
     1 => [0.0,0.0],
     2 => [1.0,0.0],