Skip to content

Commit

Permalink
doc: Move PencilGrids example to Literate.jl
Browse files Browse the repository at this point in the history 
Literate.jl eases rendering scripts and their output in documentation
built by Documenter.jl.  This should make the examples much more
prominent and keep them up to date.

This commit refreshes the MPI/PencilGrids example and uses Literate.jl
to render it in the docs.
  • Loading branch information
@musoke
musoke committed Jun 25, 2024
1 parent c3e02ab commit 9ff8447
Show file tree
Hide file tree
Showing 5 changed files with 144 additions and 107 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@

/docs/build/
/docs/Manifest.toml
/docs/src/examples

/test/Manifest.toml

Expand Down
72 changes: 30 additions & 42 deletions docs/Manifest.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

julia_version = "1.10.2"
manifest_format = "2.0"
project_hash = "98964fba5f331f7f5e0df09b4f7cad34c39885fc"
project_hash = "05ea43fa36693c647d8a75059fa294fd7665bcdf"

[[deps.ANSIColoredPrinters]]
git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c"
Expand Down Expand Up @@ -301,9 +301,9 @@ version = "1.16.0"

[[deps.DataStructures]]
deps = ["Compat", "InteractiveUtils", "OrderedCollections"]
git-tree-sha1 = "0f4b5d62a88d8f59003e43c25a8a90de9eb76317"
git-tree-sha1 = "97d79461925cdb635ee32116978fc735b9463a39"
uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
version = "0.18.18"
version = "0.18.19"

[[deps.DataValueInterfaces]]
git-tree-sha1 = "bfc1187b79289637fa0ef6d4436ebdfe6905cbd6"
Expand Down Expand Up @@ -371,9 +371,9 @@ version = "0.9.3"

[[deps.Documenter]]
deps = ["ANSIColoredPrinters", "AbstractTrees", "Base64", "CodecZlib", "Dates", "DocStringExtensions", "Downloads", "Git", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "MarkdownAST", "Pkg", "PrecompileTools", "REPL", "RegistryInstances", "SHA", "TOML", "Test", "Unicode"]
git-tree-sha1 = "4a40af50e8b24333b9ec6892546d9ca5724228eb"
git-tree-sha1 = "f15a91e6e3919055efa4f206f942a73fedf5dfe6"
uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
version = "1.3.0"
version = "1.4.0"

[[deps.DocumenterInterLinks]]
deps = ["CodecZlib", "DocInventories", "Documenter", "DocumenterInventoryWritingBackport", "Markdown", "MarkdownAST", "TOML"]
Expand Down Expand Up @@ -489,9 +489,9 @@ weakdeps = ["PDMats", "SparseArrays", "Statistics"]

[[deps.FiniteDiff]]
deps = ["ArrayInterface", "LinearAlgebra", "Requires", "Setfield", "SparseArrays"]
git-tree-sha1 = "bc0c5092d6caaea112d3c8e3b238d61563c58d5f"
git-tree-sha1 = "2de436b72c3422940cbe1367611d137008af7ec3"
uuid = "6a86dc24-6348-571c-b903-95158fe2bd41"
version = "2.23.0"
version = "2.23.1"

[deps.FiniteDiff.extensions]
FiniteDiffBandedMatricesExt = "BandedMatrices"
Expand Down Expand Up @@ -640,10 +640,10 @@ weakdeps = ["MPI"]
MPIExt = "MPI"

[[deps.HDF5_jll]]
deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "LLVMOpenMP_jll", "LazyArtifacts", "LibCURL_jll", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "OpenSSL_jll", "TOML", "Zlib_jll", "libaec_jll"]
git-tree-sha1 = "38c8874692d48d5440d5752d6c74b0c6b0b60739"
deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "LazyArtifacts", "LibCURL_jll", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "OpenSSL_jll", "TOML", "Zlib_jll", "libaec_jll"]
git-tree-sha1 = "82a471768b513dc39e471540fdadc84ff80ff997"
uuid = "0234f1f7-429e-5d53-9886-15a909be8d59"
version = "1.14.2+1"
version = "1.14.3+3"

[[deps.HarfBuzz_jll]]
deps = ["Artifacts", "Cairo_jll", "Fontconfig_jll", "FreeType2_jll", "Glib_jll", "Graphite2_jll", "JLLWrappers", "Libdl", "Libffi_jll", "Pkg"]
Expand Down Expand Up @@ -754,9 +754,9 @@ version = "0.15.1"

[[deps.IntervalArithmetic]]
deps = ["CRlibm_jll", "MacroTools", "RoundingEmulator"]
git-tree-sha1 = "a066535c05e21f8e18b18e759a5d790b7a706399"
git-tree-sha1 = "23ddd329f4a2a65c7a55b91553b60849bd038575"
uuid = "d1acc4aa-44c8-5952-acd4-ba5d80a2a253"
version = "0.22.10"
version = "0.22.11"
weakdeps = ["DiffRules", "ForwardDiff", "RecipesBase"]

[deps.IntervalArithmetic.extensions]
Expand Down Expand Up @@ -970,6 +970,12 @@ git-tree-sha1 = "d76cec8007ec123c2b681269d40f94b053473fcf"
uuid = "9b3f67b0-2d00-526e-9884-9e4938f8fb88"
version = "0.2.7"

[[deps.Literate]]
deps = ["Base64", "IOCapture", "JSON", "REPL"]
git-tree-sha1 = "596df2daea9c27da81eee63ef2cf101baf10c24c"
uuid = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
version = "2.18.0"

[[deps.LogExpFunctions]]
deps = ["DocStringExtensions", "IrrationalConstants", "LinearAlgebra"]
git-tree-sha1 = "18144f3e9cbe9b15b070288eef858f71b291ce37"
Expand Down Expand Up @@ -997,9 +1003,9 @@ version = "2024.0.0+0"

[[deps.MPI]]
deps = ["Distributed", "DocStringExtensions", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "PkgVersion", "PrecompileTools", "Requires", "Serialization", "Sockets"]
git-tree-sha1 = "b4d8707e42b693720b54f0b3434abee6dd4d947a"
git-tree-sha1 = "4e3136db3735924f96632a5b40a5979f1f53fa07"
uuid = "da04e1cc-30fd-572f-bb4f-1f8673147195"
version = "0.20.16"
version = "0.20.19"

[deps.MPI.extensions]
AMDGPUExt = "AMDGPU"
Expand Down Expand Up @@ -1146,9 +1152,9 @@ uuid = "510215fc-4207-5dde-b226-833fc4488ee2"
version = "0.5.5"

[[deps.OffsetArrays]]
git-tree-sha1 = "6a731f2b5c03157418a20c12195eb4b74c8f8621"
git-tree-sha1 = "e64b4f5ea6b7389f6f046d13d4896a8f9c1ba71e"
uuid = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
version = "1.13.0"
version = "1.14.0"
weakdeps = ["Adapt"]

[deps.OffsetArrays.extensions]
Expand Down Expand Up @@ -1183,10 +1189,10 @@ uuid = "05823500-19ac-5b8b-9628-191a04bc5112"
version = "0.8.1+2"

[[deps.OpenMPI_jll]]
deps = ["Artifacts", "CompilerSupportLibraries_jll", "Hwloc_jll", "JLLWrappers", "LazyArtifacts", "Libdl", "MPIPreferences", "PMIx_jll", "TOML", "Zlib_jll", "libevent_jll", "prrte_jll"]
git-tree-sha1 = "f46caf663e069027a06942d00dced37f1eb3d8ad"
deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "LazyArtifacts", "Libdl", "MPIPreferences", "TOML"]
git-tree-sha1 = "e25c1778a98e34219a00455d6e4384e017ea9762"
uuid = "fe0851c0-eecd-5654-98d4-656369965a5c"
version = "5.0.2+0"
version = "4.1.6+0"

[[deps.OpenSSL_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl"]
Expand Down Expand Up @@ -1234,12 +1240,6 @@ git-tree-sha1 = "949347156c25054de2db3b166c52ac4728cbad65"
uuid = "90014a1f-27ba-587c-ab20-58faa44d9150"
version = "0.11.31"

[[deps.PMIx_jll]]
deps = ["Artifacts", "Hwloc_jll", "JLLWrappers", "Libdl", "Zlib_jll", "libevent_jll"]
git-tree-sha1 = "360f48126b5f2c2f0c833be960097f7c62705976"
uuid = "32165bc3-0280-59bc-8c0b-c33b6203efab"
version = "4.2.9+0"

[[deps.PNGFiles]]
deps = ["Base64", "CEnum", "ImageCore", "IndirectArrays", "OffsetArrays", "libpng_jll"]
git-tree-sha1 = "67186a2bc9a90f9f85ff3cc8277868961fb57cbd"
Expand Down Expand Up @@ -1330,9 +1330,9 @@ version = "0.1.2"

[[deps.Polynomials]]
deps = ["LinearAlgebra", "RecipesBase", "Setfield", "SparseArrays"]
git-tree-sha1 = "a9c7a523d5ed375be3983db190f6a5874ae9286d"
git-tree-sha1 = "81a2a9462003a423fdc59e2a3ff84cde93c4637b"
uuid = "f27b6e38-b328-58d1-80ce-0feddd5e7a45"
version = "4.0.6"
version = "4.0.7"

[deps.Polynomials.extensions]
PolynomialsChainRulesCoreExt = "ChainRulesCore"
Expand Down Expand Up @@ -1797,10 +1797,10 @@ deps = ["Random", "SHA"]
uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"

[[deps.UltraDark]]
deps = ["AbstractFFTs", "Dates", "FFTW", "Folds", "HDF5", "LinearAlgebra", "MPI", "NPZ", "PencilArrays", "PencilFFTs", "PrecompileTools", "Statistics", "Strided"]
git-tree-sha1 = "0ee24e6baad120e1e56c49db4b77aafb8517ff68"
deps = ["AbstractFFTs", "Dates", "DocStringExtensions", "FFTW", "Folds", "HDF5", "LinearAlgebra", "MPI", "NPZ", "PencilArrays", "PencilFFTs", "PrecompileTools", "Statistics", "Strided"]
git-tree-sha1 = "f22903afb21f84c2a3ba0109b436ed54dc53f6e0"
uuid = "1c8d022d-dfc0-4b41-80ab-3fc7e88cdfea"
version = "0.9.6"
version = "0.9.7"

[[deps.UnPack]]
git-tree-sha1 = "387c1f73762231e86e0c9c5443ce3b4a0a9a0c2b"
Expand Down Expand Up @@ -1927,12 +1927,6 @@ deps = ["Artifacts", "Libdl"]
uuid = "8e850b90-86db-534c-a0d3-1478176c7d93"
version = "5.8.0+1"

[[deps.libevent_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl", "OpenSSL_jll"]
git-tree-sha1 = "f04ec6d9a186115fb38f858f05c0c4e1b7fc9dcb"
uuid = "1080aeaf-3a6a-583e-a51c-c537b09f60ec"
version = "2.1.13+1"

[[deps.libfdk_aac_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg"]
git-tree-sha1 = "daacc84a041563f965be61859a36e17c4e4fcd55"
Expand Down Expand Up @@ -1967,12 +1961,6 @@ deps = ["Artifacts", "Libdl"]
uuid = "3f19e933-33d8-53b3-aaab-bd5110c3b7a0"
version = "17.4.0+2"

[[deps.prrte_jll]]
deps = ["Artifacts", "Hwloc_jll", "JLLWrappers", "Libdl", "PMIx_jll", "libevent_jll"]
git-tree-sha1 = "5adb2d7a18a30280feb66cad6f1a1dfdca2dc7b0"
uuid = "eb928a42-fffd-568d-ab9c-3f5d54fc65b9"
version = "3.0.2+0"

[[deps.x264_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg"]
git-tree-sha1 = "4fea590b89e6ec504593146bf8b988b2c00922b2"
Expand Down
3 changes: 3 additions & 0 deletions docs/Project.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,12 @@ CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
MPI = "da04e1cc-30fd-572f-bb4f-1f8673147195"
NPZ = "15e1cf62-19b3-5cfa-8e77-841668bca605"
UltraDark = "1c8d022d-dfc0-4b41-80ab-3fc7e88cdfea"

[compat]
Documenter = "1"
DocumenterInterLinks = "0.3"
Literate = "2.18"
24 changes: 23 additions & 1 deletion docs/make.jl
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
using Documenter
using DocumenterInterLinks
using Literate
using UltraDark

links = InterLinks(
Expand All @@ -14,6 +15,26 @@ links = InterLinks(

fallbacks = ExternalFallbacks()

# Use Literate.jl to convert *.jl examples to markdown files included in docs
const LITERATE_OUTPUT = joinpath(@__DIR__, "src", "examples")
const LITERATE_INPUT = joinpath(@__DIR__, "..", "examples")

for (root, _, files) in walkdir(LITERATE_INPUT), file in files
# ignore non julia files
splitext(file)[2] == ".jl" || continue

# full path to a literate script
ipath = joinpath(root, file)

# generated output path
opath = splitdir(replace(ipath, LITERATE_INPUT => LITERATE_OUTPUT))[1]

# generate the Literate output
Literate.script(ipath, opath)
Literate.markdown(ipath, opath)
Literate.notebook(ipath, opath)
end

makedocs(;
modules = [UltraDark],
format = Documenter.HTML(;
Expand All @@ -31,6 +52,7 @@ makedocs(;
"Simulation Configuration"=>"man/config.md",
"Summary Statistics"=>"man/summary.md",
],
"Examples" => Any["PencilGrids"=>"examples/soliton_velocity.md",],
"API" => "api.md",
],
repo = Remotes.GitHub("musoke", "UltraDark.jl"),
Expand All @@ -39,4 +61,4 @@ makedocs(;
plugins = [links, fallbacks],
)

deploydocs(; repo = "github.com/musoke/UltraDark.jl", devbranch = "main")
deploydocs(; repo = "https://github.com/musoke/UltraDark.jl", devbranch = "main")
Loading

0 comments on commit 9ff8447

Please sign in to comment.