Restructure tutorials into tutorials/howto/gallery

.gitignore

@@ -11,6 +11,8 @@ docs/build/
 docs/site/
 docs/src/examples/
 docs/src/tutorials/
+docs/src/howto/
+docs/src/gallery/
 *.DS_Store
 /Manifest.toml
 /test/coverage/Manifest.toml

docs/generate.jl

@@ -1,24 +1,30 @@
 # generate examples
 import Literate
 
-TUTORIALS_IN = joinpath(@__DIR__, "src", "literate")
+# Tutorials
+TUTORIALS_IN = joinpath(@__DIR__, "src", "literate-tutorials")
 TUTORIALS_OUT = joinpath(@__DIR__, "src", "tutorials")
 mkpath(TUTORIALS_OUT)
 
+# How-to guides
 HOWTO_IN = joinpath(@__DIR__, "src", "literate-howto")
 HOWTO_OUT = joinpath(@__DIR__, "src", "howto")
-mkpath(HOWTO_IN)
 mkpath(HOWTO_OUT)
 
+# Code gallery
+GALLERY_IN = joinpath(@__DIR__, "src", "literate-gallery")
+GALLERY_OUT = joinpath(@__DIR__, "src", "gallery")
+mkpath(GALLERY_OUT)
+
 # Download some assets
 include("download_resources.jl")
 
 # Run Literate on all examples
-@timeit dto "Literate." for tutorial in readdir(TUTORIALS_IN; join=true)
-    name = basename(tutorial)
-    if endswith(tutorial, ".jl")
+@timeit dto "Literate." for (IN, OUT) in [(TUTORIALS_IN, TUTORIALS_OUT), (HOWTO_IN, HOWTO_OUT), (GALLERY_IN, GALLERY_OUT)], program in readdir(IN; join=true)
+    name = basename(program)
+    if endswith(program, ".jl")
         if !liveserver
-            script = @timeit dto "script()" @timeit dto name Literate.script(tutorial, TUTORIALS_OUT)
+            script = @timeit dto "script()" @timeit dto name Literate.script(program, OUT)
             code = strip(read(script, String))
         else
             code = "<< no script output when building as draft >>"
@@ -38,22 +44,24 @@ include("download_resources.jl")
         end
 
         @timeit dto "markdown()" @timeit dto name begin
-            Literate.markdown(tutorial, TUTORIALS_OUT, postprocess = mdpost)
+            Literate.markdown(program, OUT, postprocess = mdpost)
         end
         if !liveserver
             @timeit dto "notebook()"  @timeit dto name begin
-                Literate.notebook(tutorial, TUTORIALS_OUT, preprocess = nbpre, execute = is_ci) # Don't execute locally
+                Literate.notebook(program, OUT, preprocess = nbpre, execute = is_ci) # Don't execute locally
             end
         end
-    elseif any(endswith.(tutorial, [".png", ".jpg", ".gif"]))
-        cp(tutorial, joinpath(TUTORIALS_OUT, name); force=true)
+    elseif any(endswith.(program, [".png", ".jpg", ".gif"]))
+        cp(program, joinpath(OUT, name); force=true)
     else
-        @warn "ignoring $tutorial"
+        @warn "ignoring $program"
     end
 end
 
 # remove any .vtu files in the generated dir (should not be deployed)
-@timeit dto "remove vtk files" cd(TUTORIALS_OUT) do
-    foreach(file -> endswith(file, ".vtu") && rm(file), readdir())
-    foreach(file -> endswith(file, ".pvd") && rm(file), readdir())
+@timeit dto "remove vtk files" for dir in [TUTORIALS_OUT, HOWTO_OUT, GALLERY_OUT]
+    cd(dir) do
+        foreach(file -> endswith(file, ".vtu") && rm(file), readdir())
+        foreach(file -> endswith(file, ".pvd") && rm(file), readdir())
+    end
 end

docs/liveserver.jl

@@ -26,12 +26,14 @@ LiveServer.servedocs(;
         # to avoid infinite loops where running make.jl updates watched files,
         # which then triggers a new run of make.jl etc.
         joinpath(repo_root, "docs/src/tutorials"),
+        joinpath(repo_root, "docs/src/howto"),
+        joinpath(repo_root, "docs/src/gallery"),
     ],
     include_files = [
+        joinpath(repo_root, "docs/generate.jl"),
         # Watch the index files in the skip_dirs folders
         joinpath(repo_root, "docs/src/tutorials/index.md"),
-        joinpath(repo_root, "docs/src/topics/index.md"),
-        joinpath(repo_root, "docs/src/reference/index.md"),
         joinpath(repo_root, "docs/src/howto/index.md"),
+        joinpath(repo_root, "docs/src/gallery/index.md"),
     ],
 )

docs/make.jl

@@ -34,20 +34,15 @@ include("generate.jl")
         "Tutorials" => [
             "Tutorials overview" => "tutorials/index.md",
             "tutorials/heat_equation.md",
-            "tutorials/postprocessing.md",
-            "tutorials/helmholtz.md",
+            "tutorials/linear_elasticity.md",
             "tutorials/incompressible_elasticity.md",
             "tutorials/hyperelasticity.md",
-            "tutorials/threaded_assembly.md",
             "tutorials/plasticity.md",
             "tutorials/transient_heat_equation.md",
-            "tutorials/landau.md",
-            "tutorials/linear_shell.md",
-            "tutorials/quasi_incompressible_hyperelasticity.md",
-            "tutorials/ns_vs_diffeq.md",
             "tutorials/computational_homogenization.md",
             "tutorials/stokes-flow.md",
-            "tutorials/topology_optimization.md",
+            "tutorials/ns_vs_diffeq.md",
+            "tutorials/linear_shell.md",
         ],
         "Topic guides" => [
             "Topic guide overview" => "topics/index.md",
@@ -73,7 +68,17 @@ include("generate.jl")
         ],
         "How-to guides" => [
             "How-to guide overview" => "howto/index.md",
+            "howto/postprocessing.md",
+            "howto/threaded_assembly.md",
         ],
+        "gallery/index.md",
+        # "Code gallery" => [
+        #     "Code gallery overview" => "gallery/index.md",
+        #     "gallery/helmholtz.md",
+        #     "gallery/quasi_incompressible_hyperelasticity.md",
+        #     "gallery/landau.md",
+        #     "gallery/topology_optimization.md",
+        # ],
         "devdocs/index.md",
         ],
 )
@@ -83,6 +88,15 @@ include("generate.jl")
     foreach(file -> endswith(file, ".vtu") && rm(file), readdir())
 end
 
+# Insert some <br> in the side menu
+for (root, _, files) in walkdir(joinpath(@__DIR__, "build")), file in joinpath.(root, files)
+    endswith(file, ".html") || continue
+    str = read(file, String)
+    # Insert <br> after "Reference" (before "Code gallery")
+    str = replace(str, r"""(<li(?: class="is-active")?><a class="tocitem" href(?:="[\./\w]+")?>Code gallery</a></li>)""" => s"<br>\1")
+    write(file, str)
+end
+
 
 # Deploy built documentation
 if !liveserver

docs/src/gallery/index.md

@@ -0,0 +1,51 @@
+# Code gallery
+
+This page gives an overview of the code gallery. Compared to the tutorials, these programs
+do not focus on teaching Ferrite, but rather focus on showing how Ferrite can be used "in
+the wild".
+
+!!! note "Contribute to the gallery!"
+    Most of the gallery is user contributed. If you use Ferrite, and have something you want
+    to share, please contribute to the gallery! This could, for example, be your research
+    code for a published paper, some interesting application, or just some nice trick.
+
+---
+
+#### [Helmholtz equation](../helmholtz/)
+
+Solves the Helmholtz equation on the unit square using a combination of Dirichlet and
+Neumann boundary conditions and the method of manufactured solutions.
+
+*Contributed by*: Kristoffer Carlsson ([@KristofferC](https://github.com/KristofferC)).
+
+---
+
+#### [Nearly incompressible hyperelasticity](../quasi_incompressible_hyperelasticity/)
+
+This program combines the ideas from [Tutorial 3: Incompressible
+elasticity](../../tutorials/incompressible_elasticity/) and [Tutorial 4:
+Hyperelasticity](../../tutorials/incompressible_elasticity/) to construct a mixed element
+solving three-dimensional displacement-pressure equations.
+
+*Contributed by*: Bhavesh Shrimali ([@bhaveshshrimali](https://github.com/bhaveshshrimali)).
+
+---
+
+#### [Ginzburg-Landau model energy minimization](../landau/)
+
+A basic Ginzburg-Landau model is solved.
+[ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) is used to compute the
+gradient and hessian of the energy function. Multi-threading is used to parallelize the
+assembly procedure.
+
+*Contributed by*: Louis Ponet ([@louisponet](https://github.com/louisponet)).
+
+---
+
+#### [Topology optimization](../topology_optimization/)
+
+Topology optimization is shown for the bending problem by using a SIMP material model. To
+avoid numerical instabilities, a regularization scheme requiring the calculation of the
+Laplacian is imposed, which is done by using the grid topology functionalities.
+
+*Contributed by*: Mischa Blaszczyk ([@blaszm](https://github.com/blaszm)).

docs/src/howto/index.md

@@ -1,3 +1,28 @@
 # How-to guides
 
-Please contribute :)
+This page gives an overview of the *how-to guides*. How-to guides address various common
+tasks one might want to do in a finite element program. Many of the guides are extensions,
+or build on top of, the tutorials and, therefore, some familiarity with Ferrite is assumed.
+
+---
+
+#### [Post processing and visualization](../postprocessing/)
+
+This guide builds on top of [Tutorial 1: Heat equation](../../tutorials/heat_equation/) and
+discusses various post processsing techniques with the goal of visualizing primary fields
+(the finite element solution) and secondary quantities (e.g. fluxes, stresses, etc.).
+Concretely, this guide answers:
+ - How to visualize data from quadrature points?
+ - How to evaluate the finite element solution, or secondary quantities, in arbitrary points
+   of the domain?
+
+---
+
+#### [Multi-threaded assembly](../threaded_assembly/)
+
+This guide modifies [Tutorial 2: Linear elasticity](../../tutorials/linear_elasticity/) such
+that the program is using multi-threading to parallelize the assembly procedure. Concretely
+this shows how to use grid coloring and "scratch values" in order to use multi-threading
+without running into race-conditions.
+
+---

docs/src/index.md

@@ -36,6 +36,8 @@ for. The document is organized as follows[^1]:
 
 [^1]: The organization of the document follows the [Diátaxis Framework](https://diataxis.fr).
 
+In addition there is a [**Code gallery**](gallery/), with user contributed example programs,
+and the [**Developer documentation**](devdocs/), for documentation of Ferrite internal code.
 
 ## Getting started
 

docs/src/literate/postprocessing.jl → docs/src/literate-howto/postprocessing.jl

@@ -1,4 +1,4 @@
-# # [Postprocessing](@id tutorial-postprocessing)
+# # [Post processing and visualization](@id howto-postprocessing)
 #
 # ![](heat_square_fluxes.png)
 #
@@ -40,7 +40,7 @@
 # ## Implementation
 #
 # Start by simply running the Heat equation example to solve the problem
-include("heat_equation.jl");
+include("../tutorials/heat_equation.jl");
 
 
 # Next we define a function that computes the heat flux for each integration point in the domain.

docs/src/literate/threaded_assembly.jl → docs/src/literate-howto/threaded_assembly.jl

@@ -1,4 +1,4 @@
-# # [Threaded Assembly](@id tutorial-threaded-assembly)
+# # [Multi-threaded assembly](@id tutorial-threaded-assembly)
 #
 #-
 #md # !!! tip

docs/src/literate/heat_equation.jl → docs/src/literate-tutorials/heat_equation.jl

@@ -1,4 +1,4 @@
-# # [Heat Equation](@id tutorial-heat-equation)
+# # [Heat equation](@id tutorial-heat-equation)
 #
 # ![](heat_square.png)
 #

docs/src/literate/hyperelasticity.jl → docs/src/literate-tutorials/hyperelasticity.jl

@@ -168,7 +168,7 @@ function constitutive_driver(C, mp::NeoHooke)
     return S, ∂S∂C
 end;
 
-# ## Newton's Method
+# ## Newton's method
 #
 # As mentioned above, to deal with the non-linear weak form we first linearize
 # the problem such that we can apply Newton's method, and then apply the FEM to

docs/src/literate/incompressible_elasticity.jl → docs/src/literate-tutorials/incompressible_elasticity.jl

@@ -1,4 +1,4 @@
-# # [Incompressible Elasticity](@id tutorial-incompressible-elasticity)
+# # [Incompressible elasticity](@id tutorial-incompressible-elasticity)
 #
 #-
 #md # !!! tip

docs/src/literate-tutorials/linear_elasticity.jl

@@ -0,0 +1,3 @@
+# # Linear elasticity
+#
+# TBW

docs/src/literate/ns_vs_diffeq.jl → docs/src/literate-tutorials/ns_vs_diffeq.jl

@@ -1,4 +1,4 @@
-# # [Incompressible Navier-Stokes Equations via DifferentialEquations.jl](@id tutorial-ins-ordinarydiffeq)
+# # [Incompressible Navier-Stokes equations via DifferentialEquations.jl](@id tutorial-ins-ordinarydiffeq)
 #
 # ![](https://user-images.githubusercontent.com/9196588/134514213-76d91d34-19ab-47c2-957e-16bb0c8669e1.gif)
 #
@@ -24,9 +24,9 @@
 # the spatial discretization of all linear and nonlinear operators depending on $u$ and $t$,
 # but not on the time derivative of $u$.
 #
-# ## Some Theory on the Incompressible Navier-Stokes Equations
+# ## Some theory on the incompressible Navier-Stokes equations
 #
-# ### Problem Description in Strong Form
+# ### Problem description in strong form
 #
 # The incompressible Navier-Stokes equations can be stated as the system
 # ```math
@@ -107,7 +107,7 @@
 # in the implementation and only stated for clarity in this section.
 #
 #
-# ## Commented Implementation
+# ## Commented implementation
 #
 # Now we solve the problem with Ferrite and [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl). What follows is a program spliced with comments.
 # The full program, without comments, can be found in the next [section](@ref ns_vs_diffeq-plain-program).

docs/src/literate/plasticity.jl → docs/src/literate-tutorials/plasticity.jl

@@ -1,4 +1,4 @@
-# # [von Mises plasticity](@id tutorial-plasticity)
+# # [Von Mises plasticity](@id tutorial-plasticity)
 #
 # ![Shows the von Mises stress distribution in a cantilever beam.](plasticity.png)
 #

docs/src/literate/transient_heat_equation.jl → docs/src/literate-tutorials/transient_heat_equation.jl

@@ -1,4 +1,4 @@
-# # [Time Dependent Problems](@id tutorial-transient-heat-equation)
+# # [Transient heat equation](@id tutorial-transient-heat-equation)
 #
 # ![](transient_heat.gif)
 # ![](transient_heat_colorbar.svg)