Add clarification in Docs regarding running examples about geophysicalflows.jl

[francispoulin]

Some thoughts on the docs. Please ignore whatever you like, since you are the experts of ourse.

• Home: In the overview you could menton that you have a lot of geophysical exams written to date but it's easy to generalize this to other PDEs.

• Installations instructions: Maybe add that yo press backspace or control-C to leave this environment afterwards? I had to look that up being a newbie.

• Code Basics:
  In first sentence after first equation maybe say that sometimes it is better to put linear terms in the nonlinear part depending on the efficiency of the solvers (or something else?). I'm thinking about the linera SW problem where you do this because presumably the solver is faster.
  Maybe mention that in most systems L is a 1D array, so a vector?
  Typo? Suggest: For example, if u has only **l depends only in one spatial dimension,
  In the range of k maybe put a cap fo n_x/2 -1 or something? Since it's necessarily finite.

• Grids:
  I did run this by mostly copying and pasting. Sadly, I couldn't figure out how to get \partial_x. I got the partial but the subscript eluded me.
  I admit that I find the ldiv! confusing, not knowing Julia, yet. Interesting, and suprising to me, that you recover \partial_x u by using a system solve but great that you can do this!

• Problem:
  I would just add the using in the same block before "nx, Lx ..." and mention that because Julia wants to be efficient, you need to load in functions when you need them. Or something to that affect.
  It's great that Julia gives you the output after grid = OneDGrid(nx, Lx). What is this called?
  Can you say a sentence as to why you use struct? In Python I presume you would use classes, but I could be wrong. I think it's great how you have it so nearly structured by the way!
  I was wondering about the definition of struct and found this "It is possible but tedious to define two structs, where one extends the other by extra fields. The relationship between the two is then made clear with an abstract and <: declaration." Maybe paraphrase this or something to explain a bit of what you are doing?
  Maybe mention what time steppers are currently avaible or mention a couple?
  I like the clock feature!
  I presume three is a way to list the variables in prob.vars. Can you state that? This case there is only u and uh, but in SW there would be several.
  You direct the reader to Diffusion in src but I don't see it there. Should it be?

• GPU:
  Here you have "using" which is great!

• Examples
  Type "For this problem Vars includes the representations"
  Are Aphys and Atrans place holders or do they mean something in particular?
  You have all the equal signs lined up except for in the block after "Construct the structs and you are ready to go!". Do you want to align those?

[francispoulin]

I'm happy to help with this but not sure what the best way of doing this is. Would you like me to add questions and comments in here or instead markup the docs?

Let me know what you prefer and I can dedicate some time to this tomorrow.

[navidcy]

This was mostly a placeholder for me to remember :)
But if you have some questions that emerged while trying to do this wouldn't hurt to point them out. Only if you have time... otherwise I'll ping you as soon as I make an attempt to include something in the docs :)

[navidcy]

CliMA/Oceananigans.jl#1149 is relevant

[navidcy]

Also, most of what discussed here revolves around Docs of FourierFlows.jl and, therefore, the issue is moved to FourierFlows/FourierFlows.jl#226