Documentation Overhaul (#231)

This works on the documentation pages to speed up their execution, prevent the hanging issue in `halmo.md` and in general clean up the pages.

.gitignore

@@ -6,3 +6,4 @@
 .vscode
 .buildkite/toolbox/config.json
 .buildkite/toolbox/username
+docs/Manifest.toml

docs/Project.toml

@@ -1,5 +1,4 @@
 [deps]
-AlgebraicPetri = "4f99eebe-17bf-4e98-b6a1-2c4f205a959b"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Catlab = "134e5e36-593f-5add-ad60-77f754baafbe"
@@ -10,16 +9,15 @@ DiagrammaticEquations = "6f00c28b-6bed-4403-80fa-30e0dc12f317"
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-DynamicalSystems = "61744808-ddfa-5f27-97ff-6e42cc95d634"
+Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
 GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
-HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 MLStyle = "d8e11817-5142-5d16-987a-aa16d5891078"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
-ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"

docs/docinfo.jl

@@ -0,0 +1,26 @@
+module DocInfo
+
+using Dates
+
+mutable struct Info
+  start_time::DateTime
+  finish_time::DateTime
+end
+
+function Info()
+  Info(now(), now())
+end
+
+function get_elapsed(info::Info)
+  info.finish_time - info.start_time
+end
+
+function get_report(info::Info)
+  info.finish_time = now()
+  elapsed = get_elapsed(info)
+  elapsed_sec = round(elapsed, Dates.Second(1))
+  @info "Page built in $(elapsed_sec)."
+  @info "This page was last built at $(info.finish_time)."
+end
+
+end

docs/make.jl

@@ -1,13 +1,10 @@
+@info "Loading Documenter"
 using Documenter
 using Literate
 using Distributed
 
 @info "Loading Decapodes"
 using Decapodes
-using Catlab
-using Catlab.WiringDiagrams
-using AlgebraicPetri
-using CairoMakie
 
 # Set Literate.jl config if not being compiled on recognized service.
 config = Dict{String,String}()
@@ -43,24 +40,25 @@ makedocs(
   sitename  = "Decapodes.jl",
   doctest   = false,
   checkdocs = :none,
+  pagesonly = true,
+  linkcheck = true,
+  linkcheck_ignore = [r"agupubs.onlinelibrary.wiley.com"], # This gives a 403 Forbidden
   pages     = Any[
     "Decapodes.jl" => "index.md",
+    "Overview" => "overview/overview.md",
+    "Equations" => "equations/equations.md",
     "Vortices" => "navier_stokes/ns.md",
-    "Halfar-NS" => "halmo.md",
-    "Overview" => "overview.md",
-    "Klausmeier" => "klausmeier.md",
-    "Glacial Flow" => "ice_dynamics.md",
-    "Grigoriev Ice Cap" => "grigoriev.md",
-    "Budyko-Sellers-Halfar" => "budyko_sellers_halfar.md",
-    "CISM v2.1" => "cism.md",
-    "NHS" => "nhs.md",
-    "Equations" => "equations.md",
+    "Cahn-Hilliard" => "ch/cahn-hilliard.md",
+    "Klausmeier" => "klausmeier/klausmeier.md",
+    "CISM v2.1" => "cism/cism.md",
+    "Glacial Flow" => "ice_dynamics/ice_dynamics.md",
+    "Grigoriev Ice Cap" => "grigoriev/grigoriev.md", # Requires ice_dynamics
+    "Budyko-Sellers-Halfar" => "bsh/budyko_sellers_halfar.md", # Requires ice_dynamics
+    "Halfar-NS" => "halmo/halmo.md", # Requires grigoriev
+    "NHS" => "nhs/nhs_lite.md",
+    "Pipe Flow" => "poiseuille/poiseuille.md",
+    "Misc Features" => "bc/bc_debug.md", # Requires overview
     "ASCII Operators" => "ascii.md",
-    "Misc Features" => "bc_debug.md",
-    "Pipe Flow" => "poiseuille.md",
-    # "Examples" => Any[
-    #   "examples/cfd_example.md"
-    # ],
     "Canonical Models" => "canon.md",
     "Library Reference" => "api.md"
   ]

docs/src/api.md

@@ -1,7 +1,17 @@
 # Library Reference
 
+```@setup INFO
+include(joinpath(Base.@__DIR__, "..", "docinfo.jl"))
+info = DocInfo.Info()
+```
+
 ## Decapodes
+
 ```@autodocs
 Modules = [ Decapodes ]
 Private = false
 ```
+
+```@example INFO
+DocInfo.get_report(info) # hide
+```

docs/src/ascii.md

@@ -1,5 +1,10 @@
 # ASCII and Vector Calculus Operators
 
+```@setup INFO
+include(joinpath(Base.@__DIR__, "..", "docinfo.jl"))
+info = DocInfo.Info()
+```
+
 Some users may have trouble entering unicode characters like ⋆ or ∂ in their development environment. So, we offer the following ASCII equivalents. Further, some users may like to use vector calculus symbols instead of exterior calculus symbols where possible. We offer support for such symbols as well.
 
 ## ASCII Equivalents
@@ -25,3 +30,6 @@ Some users may have trouble entering unicode characters like ⋆ or ∂ in their
 | ∇x       | ∘(d,⋆)           | \nabla \<tab\> x            |
 | adv(X,Y) | ∘(⋆,d,⋆)(X∧Y)    | adv                         |
 
+```@example INFO
+DocInfo.get_report(info) # hide
+```

docs/src/bc_debug.md → docs/src/bc/bc_debug.md

@@ -1,22 +1,23 @@
 # Simulation Setup
 
+```@setup INFO
+include(joinpath(Base.@__DIR__, "..", "..", "docinfo.jl"))
+info = DocInfo.Info()
+```
+
 This tutorial showcases some of the other features included in the Decapodes.jl
 package. Currently, these features are the treatment of boundary conditions and
 the simulation debugger interface. To begin, we set up the same
-advection-diffusion problem presented in the Overview section.
+advection-diffusion problem presented in the [Overview](../overview/overview.md) section.
 As before, we define the Diffusion, Advection, and Superposition components,
-and now include a BC (Bounday Condition) component. Decapodes.jl interprets any
-`Hom` which begins with a `∂` as a boundary condition. These boundary
-conditions recieve special treatment at the scheduling step. Below we show the
+and now include a Boundary Condition (BC) component. By convention, BCs are encoded in Decapodes by using a `∂` symbol. Below we show the
 graphical rendering of this boundary condition diagram, which we will use to
-impose a Dirichlet condition on the time derivative of concentration at the
+impose a [Dirichlet condition](https://en.wikipedia.org/wiki/Dirichlet_boundary_condition) on the time derivative of concentration at the
 mesh boundary.
 
 ```@example Debug
 using Catlab
-using Catlab.Graphics
 using DiagrammaticEquations
-using DiagrammaticEquations.Deca
 using Decapodes
 
 Diffusion = @decapode begin
@@ -58,7 +59,6 @@ to_graphviz(BoundaryConditions)
 
 As before, we compose these physics components over our wiring diagram.
 
-
 ```@example Debug
 compose_diff_adv = @relation (C, V) begin
   diffusion(C, ϕ₁)
@@ -67,7 +67,7 @@ compose_diff_adv = @relation (C, V) begin
   superposition(ϕ₁, ϕ₂, ϕ, C_up, C)
 end
 
-to_graphviz(compose_diff_adv, box_labels=:name, junction_labels=:variable, prog="circo")
+draw_composition(compose_diff_adv)
 ```
 
 ```@example Debug
@@ -87,11 +87,10 @@ ensures that this boundary condition holds true for any variables dependent on
 this variable, though also means that the boundary conditions on a variable
 have no immediate impact on the variables this variable is dependent on.
 
-In the visualization below, wee see that the final operation
+In the visualization below, we see that the final operation
 executed on the data is the boundary condition we are enforcing on the change
 in concentration.
 
-
 ```@example Debug
 to_graphviz(DiffusionAdvection)
 ```
@@ -101,16 +100,15 @@ boundary conditions and so we will use the `plot_mesh` from the previous
 example instead of the mesh with periodic boundary conditions. Because the mesh
 is only a primal mesh, we also generate and subdivide the dual mesh.
 
-`Rectangle_30x10` is a default mesh that is downloaded via `Artifacts.jl` when a user installs Decapodes. Via CombinatorialSpaces.jl, we can instantiate any `.obj` file of triangulated faces as a simplicial set.
-
 ```@example Debug
-using CombinatorialSpaces, CombinatorialSpaces.DiscreteExteriorCalculus
+using CombinatorialSpaces
 using CairoMakie
 
 plot_mesh = loadmesh(Rectangle_30x10())
 
 # Generate the dual mesh
 plot_mesh_dual = EmbeddedDeltaDualComplex2D{Bool, Float64, Point3{Float64}}(plot_mesh)
+
 # Calculate distances and subdivisions for the dual mesh
 subdivide_duals!(plot_mesh_dual, Circumcenter())
 
@@ -124,15 +122,14 @@ Finally, we define our operators, generate the simulation function, and compute
 the simulation. Note that when we define the boundary condition operator, we
 hardcode the boundary indices and values into the operator itself. We also move
 the initial concentration to the left, so that we are able to see a constant
-concentration on the left boundary which will act as a source in the flow. The
+concentration on the left boundary which will act as a source in the flow. You can find the file for boundary conditions [here](../boundary_helpers.jl). The
 modified initial condition is shown below:
 
 ```@example Debug
 using LinearAlgebra
 using ComponentArrays
 using MLStyle
-using CombinatorialSpaces.DiscreteExteriorCalculus: ∧
-include("../../examples/boundary_helpers.jl")
+include("../boundary_helpers.jl")
 
 function generate(sd, my_symbol; hodge=GeometricHodge())
   op = @match my_symbol begin
@@ -142,12 +139,9 @@ function generate(sd, my_symbol; hodge=GeometricHodge())
       x[boundary] .= 0
       x
     end
-    :∧₀₁ => (x,y) -> begin
-      ∧(Tuple{0,1}, sd, x,y)
-    end
     x => error("Unmatched operator $my_symbol")
   end
-  return (args...) -> op(args...)
+  return op
 end
 
 using Distributions
@@ -194,4 +188,8 @@ record(fig, "diff_adv_right.gif", range(0.0, 100.0; length=150); framerate = 30)
 end
 ```
 
-![](diff_adv_right.gif)
+![Diffusion-Advection result and your first BC Decapode!](diff_adv_right.gif)
+
+```@example INFO
+DocInfo.get_report(info) # hide
+```