Documentation Overhaul

[GeorgeR227]

All documentation pages are being reviewed and improved to clean up our pages and to cut down on the documentation building time.

[GeorgeR227]

Benchmarks for original docs build:

navier_stokes/ns - 0 seconds
halmo - 63 seconds
overview - 28 seconds (locally run)
klausmeier - 233 seconds
ice_dynamics - 68 seconds
grigoriev - 74 seconds
budyko_sellers_halfar - 57 seconds
cism - 32 seconds
nhs - 404 seconds
equations - 1 second
bc_debug - 95 seconds
poiseuille - 29 seconds

[jpfairbanks]

Great work @GeorgeR227, this is almost done. I added some inline comments.

[lukem12345]

http://go.owu.edu/~chjackso/Climate/papers/Glen_1958_The%20flow%20law%20of%20ice.pdf

…

On Fri, May 31, 2024, 3:28 PM GeorgeR227 ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/src/ice_dynamics.md <#231 (comment)> : > @@ -56,7 +61,8 @@ end to_graphviz(halfar_eq2) ``` -And here, a formulation of Glen's law from J.W. Glen's 1958 "The flow law of ice". +And here, a formulation of Glen's law from J.W. Glen's 1958 "The flow law of ice". <!-- TODO: Add a link for this too --> @lukem12345 <https://github.com/lukem12345> Can we also get a link to this paper? — Reply to this email directly, view it on GitHub <#231 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQYHBYOCO6QDJBIOM2ZHYJTZFDFORAVCNFSM6AAAAABIALOWU2VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDAOJRGU4DGNBVGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[GeorgeR227]

Benchmark times as of this last commit. These are built locally, not on HiPerGator like in #231 (comment).

navier_stokes/ns - 0 seconds
halmo - removed
overview - 30 seconds
klausmeier - 24 seconds
ice_dynamics - 42 seconds
grigoriev - 21 seconds
budyko_sellers_halfar - 25 seconds
cism - 27 seconds
nhs - 11 seconds (lite version)
equations - 1 second
bc_debug - 22 seconds
poiseuille - 9 seconds
cahn-hilliard - 165 seconds

[GeorgeR227]

For some reason halmo.md is breaking the docs build. When I remove it, the docs build fine and fairly quickly. The moment I re-include it the docs just seem to perpetually hang. I've tried building that page by itself and it seems to build fine so I'm not sure what the issue is.

[GeorgeR227]

I'm going to try going through all the files and see which ones could be causing issues with halmo.md. If I can't diagnose it then I'd want to just remove it for now from the pages so we can merge this PR.

[lukem12345]

Theory: There is a race condition.

The issue occurs (sometimes) when we generate a .jl file. Perhaps Documenter is seeing the .jl file and doing its Documenter black magic on it before the file is finished writing etc. etc.

[GeorgeR227]

Well the .jl file is removed and it's still dead-locking. Leading theory for me right now is that it is something to do with the save_vorticity function.

[GeorgeR227]

I'm not sure what to say but it seems like save_vorticity may have been the cause. I've run the docs multiple times now and it seems to work.

[GeorgeR227]

Pretty sure the issue occurs when we actually create the gif. Still not sure as to why.

[lukem12345]

Interesting. May be worth your while to look at `top` and see when `ffmpeg` spawns and terminates

…

On Tue, Jun 4, 2024, 4:30 PM GeorgeR227 ***@***.***> wrote: Pretty sure the issue occurs when we actually create the gif. Still not sure as to why. image.png (view on web) <https://github.com/AlgebraicJulia/Decapodes.jl/assets/78235421/45799b4f-6f9e-49c0-afc1-a9005875240f> — Reply to this email directly, view it on GitHub <#231 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQYHBYMF4KD74Q7ZUBC4J5DZFYPWDAVCNFSM6AAAAABIALOWU2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNBYGM3DKNBUHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[GeorgeR227]

@lukem12345 You were right about ffmpeg.exe this seems to be deadlocked and is the only program with this handle.

[GeorgeR227]

I've opted to just remove the offending code in halmo.md because I fear the hanging issue is not something we really have the ability to fix. I also still don't know the root cause of the hanging.