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

[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 https://github.com/AlgebraicJulia/Decapodes.jl/pull/231#discussion_r1622874855 :

@@ -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".

@lukem12345 https://github.com/lukem12345 Can we also get a link to this paper?

— Reply to this email directly, view it on GitHub https://github.com/AlgebraicJulia/Decapodes.jl/pull/231#pullrequestreview-2091583452, 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 https://github.com/AlgebraicJulia/Decapodes.jl/pull/231#issuecomment-2135893834.

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

[lukem12345]

Yeah that's the good one to use

On Fri, May 31, 2024, 4:56 PM GeorgeR227 @.***> wrote:

@.**** commented on this pull request.

In docs/src/ice_dynamics.md https://github.com/AlgebraicJulia/Decapodes.jl/pull/231#discussion_r1622943387 :

-We can use operadic composition to specify how our models come together. In this example, we have two Decapodes, and two quantities that are shared between them.

This one? https://arxiv.org/abs/2105.12282

— Reply to this email directly, view it on GitHub https://github.com/AlgebraicJulia/Decapodes.jl/pull/231#discussion_r1622943387, or unsubscribe https://github.com/notifications/unsubscribe-auth/AQYHBYPSXNVJOPCSMOONMFTZFDPYTAVCNFSM6AAAAABIALOWU2VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDAOJRGY4TSOBRHA . You are receiving this because you were mentioned.Message ID: @.***>

[GeorgeR227]

Adding to the benchmarks at https://github.com/AlgebraicJulia/Decapodes.jl/pull/231#issuecomment-2142895966: halmo - 54 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 https://github.com/AlgebraicJulia/Decapodes.jl/pull/231#issuecomment-2148365449, 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.