use DocumenterCodeBlocks.jl (#313)

Co-authored-by: Joshua Lampert <joshua.lampert@uni-hamburg.de>
Co-authored-by: Joshua Lampert <51029046+JoshuaLampert@users.noreply.github.com>

Author: ranocha

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCodeBlocks = "b6400b83-267f-4b55-9fd8-bffc853bdfd8"
 OrdinaryDiffEqTsit5 = "b1df2697-797e-41e3-8120-5422d3b24e4a"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
@@ -11,6 +12,7 @@ TrixiBase = "9a0f1c46-06d5-4909-a5a3-ce25d3fa3284"
 [compat]
 Changelog = "1"
 Documenter = "1"
+DocumenterCodeBlocks = "1.0"
 OrdinaryDiffEqTsit5 = "1, 2"
 Plots = "1.9"
 Printf = "1"

docs/make.jl

@@ -1,4 +1,5 @@
 using Documenter
+using DocumenterCodeBlocks: CodeBlocks
 using DispersiveShallowWater
 using TrixiBase
 using Changelog: Changelog
@@ -79,6 +80,9 @@ makedocs(;
                                   assets = ["assets/favicon.ico"],
                                   size_threshold = 1200 * 1024, # the generated .gif files can be too large
                                   size_threshold_warn = 1000 * 1024),
+         # Improve code blocks in the documentation by using DocumenterCodeBlocks.jl
+         plugins = [CodeBlocks()],
+         # Explicitly specify documentation structure
          pages = ["Home" => "index.md",
              "Overview" => "overview.md",
              "Basic Example" => "basic_example.md",

docs/src/basic_example.md

@@ -158,7 +158,7 @@ More examples sorted by the simulated equations can be found in the [examples/](
 
 Here follows a version of the program without any comments.
 
-```Julia
+```julia
 using DispersiveShallowWater, OrdinaryDiffEqTsit5
 
 equations = BBMBBMEquations1D(bathymetry_type = bathymetry_variable, gravity = 9.81)

src/equations/hyperbolic_sainte_marie_1d.jl

@@ -7,9 +7,9 @@
 
 Hyperbolic approximation of the Sainte-Marie system
 [`SainteMarieEquations1D`](@ref) in one spatial dimension
-(with parameter ``\gamma = 2`` compared to the original literature)
 derived by Escalante, Dumbser and Castro (2019).
-The equations are given by
+The equations (with parameter ``\gamma = 2`` compared to the original literature)
+are given by
 ```math
 \begin{aligned}
   h_t + (h v)_x &= 0,\\

src/solver.jl

@@ -76,7 +76,9 @@ end
 """
     Solver(D1, D2 = nothing, D3 = nothing)
 
-Create a solver, where `D1` is an `AbstractDerivativeOperator`
+Create a solver given the three summation-by-parts (SBP) first-, second-, and third-derivative operators
+`D1`, `D2`, and `D3`.
+`D1` is an `AbstractDerivativeOperator`
 from [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl)
 of first `derivative_order`, `D2` is an `AbstractDerivativeOperator`
 of second `derivative_order` or an `AbstractMatrix`, and `D3` is an `AbstractDerivativeOperator`