Balancing Docs between First Principles and Many Examples

[quffaro]

This draft PR proposes amending the documentation to balance a first-principles approach to documentation with the existing variety of examples showcasing Decapodes capabilities. This variety of simulations, as standalone examples of a Decapodes workflow, vary slightly in which capabilities they exhibit due to the particular differences within each scientific model.

The intent of this branch is to implement a structure specified in Issue 294, but because of the debate and scope of work, this first pass more modestly adds literate docs pages and reorders the documentation somewhat. The specific goals are:

1. Deduplicating explanation
2. Using Literate.jl to move examples into docs/literate
3. Documenting "tips and tricks"; making it easier for modelers to access learned wisdom from simulations (e.g., sigmoid function for boundary conditions, write/loading the gensim for debugging, and the world age issue I encountered when I tried to save the output of gensim to field in a struct)

Following the discussion in the cited Issue, I've selected ice_dynamics as the example which is sufficiently detailed and manual-like to be the guiding example of a walk-through of specifying and running a Decapodes simulation. In doing so, I intend to curb the problem of "information overload" by prioritizing for the user a complete standalone example.

This PR also moves some simulations from the examples folder into docs/literate, reviving a commented-out feature for building literate docs pages.

Question Since examples and docs both exemplify Decapodes capabilities, what is the precise reason that examples exists? If it is a directory of examples for users to copy and modify, then can they moved into the docs/literate folder so they can be rendered? If so, should the cuda examples remain in the examples folder to avoid duplicating docs builds?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 78.09%. Comparing base (f349d80) to head (6c14a51).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #296   +/-   ##
=======================================
  Coverage   78.09%   78.09%           
=======================================
  Files           5        5           
  Lines         630      630           
=======================================
  Hits          492      492           
  Misses        138      138           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jpfairbanks]

I put the Brusselator docs into the zoo after Cahn Hilliard.

[jpfairbanks]

@quffaro, can you summarize here the steps you need to do to get this merged?

[quffaro]

@quffaro, can you summarize here the steps you need to do to get this merged?

I think the most helpful things for users would be cleaning the examples to be consistent with the latest Decapodes idiom. For example on overview.md, @GeorgeR227 and I removed the generate function to just define a Constant, punting the generate lesson to a later doc, removed code that duplicated features that have been since upstreamed (e.g., flat), and expanded on some concepts in text.

Since the examples themselves already have a lot of pedagogical value, I think an acceptable stopping point would be if

1. the present markdown examples were updated as we did for overview.md
2. "Overview," "Equations," and "Meshes" are treated as subpages for a section like "Tutorial" or "Basic Concepts"

Some of the other smaller additions suggested in the issue could probably go into an FAQ section, which is on another branch.