diff --git a/README.md b/README.md index d306688a..fb0859df 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,14 @@ and provides a structured way to solve various `Ferrite.jl` problems. See the [documentation](https://KnutAM.github.io/FerriteAssembly.jl/dev) for more details. +## Building the documentation locally +Run `make -C docs` (or `julia --project=docs docs/liveserver.jl`) to build the +complete documentation and serve it at `http://localhost:8000`, rebuilding +automatically when files in `docs/` or `src/` change. This executes all tutorials +and how-tos, just like `julia --project=docs docs/make.jl`. Run `make -C docs draft` +(or pass `draft` to `docs/liveserver.jl`) to serve draft documentation without +executing the tutorials and how-tos. `make -C docs clean` removes the generated files. + ## Using with `Ferrite.jl`'s master branch This badge shows if `FerriteAssembly#main` is compatible with `Ferrite#master`. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..6576dd31 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,14 @@ +SRCDIR:=$(shell dirname $(abspath $(firstword $(MAKEFILE_LIST)))) + +default: liveserver + +liveserver: + julia --project=${SRCDIR} ${SRCDIR}/liveserver.jl + +draft: + julia --project=${SRCDIR} ${SRCDIR}/liveserver.jl draft + +clean: + julia ${SRCDIR}/clean.jl + +.PHONY: default liveserver draft clean diff --git a/docs/Manifest.toml b/docs/Manifest.toml index 43548160..b508c8f6 100644 --- a/docs/Manifest.toml +++ b/docs/Manifest.toml @@ -1,8 +1,8 @@ # This file is machine-generated - editing it directly is not advised -julia_version = "1.12.1" +julia_version = "1.12.5" manifest_format = "2.0" -project_hash = "203226657885e5dc74bab004ab15ae8e0accb187" +project_hash = "8f555d6703852ef9f3e4e24e588599c15742cf1a" [[deps.ANSIColoredPrinters]] git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c" @@ -100,6 +100,11 @@ git-tree-sha1 = "7fecfb1123b8d0232218e2da0c213004ff15358d" uuid = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf" version = "1.6.3" +[[deps.BitFlags]] +git-tree-sha1 = "bbe1079eecf9c9fbb52765193ad2bae27ae09bc8" +uuid = "d1d4a3ce-64b1-5f1a-9ba4-7e7e69966f35" +version = "0.1.10" + [[deps.Bzip2_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl"] git-tree-sha1 = "1b96ea4a01afe0ea4090c5c8039690672dd13f2e" @@ -155,6 +160,12 @@ weakdeps = ["SparseArrays"] [deps.ChainRulesCore.extensions] ChainRulesCoreSparseArraysExt = "SparseArrays" +[[deps.CodeTracking]] +deps = ["InteractiveUtils", "REPL", "UUIDs"] +git-tree-sha1 = "cfb7a2e89e245a9d5016b70323db412b3a7438d5" +uuid = "da1fd8a2-8d9e-5ec2-8556-3022fb5608a2" +version = "3.0.2" + [[deps.CodecZlib]] deps = ["TranscodingStreams", "Zlib_jll"] git-tree-sha1 = "962834c22b66e32aa10f7611c08c8ca4e20749a9" @@ -215,6 +226,11 @@ weakdeps = ["Dates", "LinearAlgebra"] [deps.Compat.extensions] CompatLinearAlgebraExt = "LinearAlgebra" +[[deps.Compiler]] +git-tree-sha1 = "382d79bfe72a406294faca39ef0c3cef6e6ce1f1" +uuid = "807dbc54-b67e-4c79-8afb-eafe4df6f2e1" +version = "0.1.1" + [[deps.CompilerSupportLibraries_jll]] deps = ["Artifacts", "Libdl"] uuid = "e66e0078-7015-5450-92f7-15fbd957f2ae" @@ -226,6 +242,12 @@ git-tree-sha1 = "cb1299fee09da21e65ec88c1ff3a259f8d0b5802" uuid = "95dc2771-c249-4cd0-9c9f-1f3b4330693c" version = "0.1.4" +[[deps.ConcurrentUtilities]] +deps = ["Serialization", "Sockets"] +git-tree-sha1 = "21d088c496ea22914fe80906eb5bce65755e5ec8" +uuid = "f0e56b4a-5159-44fe-b623-3e5288b988bb" +version = "2.5.1" + [[deps.ConstructionBase]] git-tree-sha1 = "b4b092499347b18a015186eae3042f72267106cb" uuid = "187b0558-2788-49d3-abe0-74a17ed4e7c9" @@ -327,7 +349,7 @@ version = "1.15.0" [[deps.Downloads]] deps = ["ArgTools", "FileWatching", "LibCURL", "NetworkOptions"] uuid = "f43a241f-c20a-4ad4-852c-f6b1247861c6" -version = "1.6.0" +version = "1.7.0" [[deps.EarCut_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg"] @@ -346,6 +368,12 @@ git-tree-sha1 = "83231673ea4d3d6008ac74dc5079e77ab2209d8f" uuid = "429591f6-91af-11e9-00e2-59fbe8cec110" version = "2.2.9" +[[deps.ExceptionUnwrapping]] +deps = ["Test"] +git-tree-sha1 = "d36f682e590a83d63d1c7dbd287573764682d12a" +uuid = "460bff9d-24e4-43bc-9d9f-a8973cb893f4" +version = "0.1.11" + [[deps.Expat_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl"] git-tree-sha1 = "27af30de8b5445644e8ffe3bcb0d72049c089cf1" @@ -393,7 +421,7 @@ version = "1.1.0" deps = ["ConstructionBase", "Ferrite", "ForwardDiff", "MaterialModelsBase"] path = ".." uuid = "fd21fc07-c509-4fe1-9468-19963fd5935d" -version = "0.3.6" +version = "0.3.7" [[deps.FerriteMeshParser]] deps = ["Ferrite"] @@ -406,13 +434,11 @@ deps = ["Pkg", "Requires", "UUIDs"] git-tree-sha1 = "d60eb76f37d7e5a40cc2e7c36974d864b82dc802" uuid = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549" version = "1.17.1" +weakdeps = ["HTTP"] [deps.FileIO.extensions] HTTPExt = "HTTP" - [deps.FileIO.weakdeps] - HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3" - [[deps.FilePaths]] deps = ["FilePathsBase", "MacroTools", "Reexport", "Requires"] git-tree-sha1 = "919d9412dbf53a2e6fe74af62a73ceed0bce0629" @@ -568,6 +594,12 @@ git-tree-sha1 = "53bb909d1151e57e2484c3d1b53e19552b887fb2" uuid = "42e2da0e-8278-4e71-bc24-59509adca0fe" version = "1.0.2" +[[deps.HTTP]] +deps = ["Base64", "CodecZlib", "ConcurrentUtilities", "Dates", "ExceptionUnwrapping", "Logging", "LoggingExtras", "MbedTLS", "NetworkOptions", "OpenSSL", "PrecompileTools", "Random", "SimpleBufferStream", "Sockets", "URIs", "UUIDs"] +git-tree-sha1 = "51059d23c8bb67911a2e6fd5130229113735fc7e" +uuid = "cd3eb016-35fb-5094-929b-558a96fad6f3" +version = "1.11.0" + [[deps.HarfBuzz_jll]] deps = ["Artifacts", "Cairo_jll", "Fontconfig_jll", "FreeType2_jll", "Glib_jll", "Graphite2_jll", "JLLWrappers", "Libdl", "Libffi_jll"] git-tree-sha1 = "f923f9a774fcf3f5cb761bfa43aeadd689714813" @@ -762,6 +794,12 @@ git-tree-sha1 = "4255f0032eafd6451d707a51d5f0248b8a165e4d" uuid = "aacddb02-875f-59d6-b918-886e6ef4fbf8" version = "3.1.3+0" +[[deps.JuliaInterpreter]] +deps = ["CodeTracking", "InteractiveUtils", "Random", "UUIDs"] +git-tree-sha1 = "c3d401f110454b4ea24a76be33f6ee0d7d385103" +uuid = "aa1ae85d-cabe-5617-a682-6adf51b2e16a" +version = "0.11.4" + [[deps.JuliaSyntaxHighlighting]] deps = ["StyledStrings"] uuid = "ac6e5ff7-fb65-4e79-a425-ec3bc9c03011" @@ -825,7 +863,7 @@ version = "0.6.4" [[deps.LibCURL_jll]] deps = ["Artifacts", "LibSSH2_jll", "Libdl", "OpenSSL_jll", "Zlib_jll", "nghttp2_jll"] uuid = "deac9b47-8bc7-5906-a0fe-35ac56dc84c0" -version = "8.11.1+1" +version = "8.15.0+0" [[deps.LibGit2]] deps = ["LibGit2_jll", "NetworkOptions", "Printf", "SHA"] @@ -899,6 +937,12 @@ git-tree-sha1 = "da046be6d63304f7ba9c1bb04820fb306ba1ab12" uuid = "98b081ad-f1c9-55d3-8b20-4c87d4299306" version = "2.20.1" +[[deps.LiveServer]] +deps = ["HTTP", "LoggingExtras", "MIMEs", "Sockets", "Test"] +git-tree-sha1 = "9f65b8a9989e6acb6e216785dd0c748d9569fc9b" +uuid = "16fef848-5104-11e9-1b77-fb7a48bbb589" +version = "1.5.0" + [[deps.LogExpFunctions]] deps = ["DocStringExtensions", "IrrationalConstants", "LinearAlgebra"] git-tree-sha1 = "13ca9e2586b89836fd20cccf56e57e2b9ae7f38f" @@ -919,6 +963,23 @@ version = "0.3.29" uuid = "56ddb016-857b-54e1-b83d-db4d58db5568" version = "1.11.0" +[[deps.LoggingExtras]] +deps = ["Dates", "Logging"] +git-tree-sha1 = "f00544d95982ea270145636c181ceda21c4e2575" +uuid = "e6f89c97-d47a-5376-807f-9c37f3926c36" +version = "1.2.0" + +[[deps.LoweredCodeUtils]] +deps = ["CodeTracking", "Compiler", "JuliaInterpreter"] +git-tree-sha1 = "1d4c737ab26f51ceed52ab2019c09b7660eb7440" +uuid = "6f1432cf-f94c-5a45-995e-cdbf5db27b0b" +version = "3.8.0" + +[[deps.MIMEs]] +git-tree-sha1 = "65f28ad4b594aebe22157d6fac869786a255b7eb" +uuid = "6c6e2e6c-3030-632d-7369-2d6c69616d65" +version = "0.1.4" + [[deps.MKL_jll]] deps = ["Artifacts", "IntelOpenMP_jll", "JLLWrappers", "LazyArtifacts", "Libdl", "oneTBB_jll"] git-tree-sha1 = "282cadc186e7b2ae0eeadbd7a4dffed4196ae2aa" @@ -953,12 +1014,12 @@ uuid = "d0879d2d-cac2-40c8-9cee-1863dc0c7391" version = "0.1.2" [[deps.MaterialModelsBase]] -deps = ["StaticArrays", "Tensors"] -git-tree-sha1 = "f23e50ae64f49aceab22ccc475596020beeb976b" +deps = ["ForwardDiff", "StaticArrays", "Tensors"] +git-tree-sha1 = "bc0d65963d330270c4d777d39cfba7f207cadb05" repo-rev = "main" repo-url = "https://github.com/KnutAM/MaterialModelsBase.jl.git" uuid = "af893363-701d-44dc-8b1e-d9a2c129bfc9" -version = "0.2.3" +version = "0.4.0" [[deps.MathTeXEngine]] deps = ["AbstractTrees", "Automa", "DataStructures", "FreeTypeAbstraction", "GeometryBasics", "LaTeXStrings", "REPL", "RelocatableFolders", "UnicodeFun"] @@ -966,13 +1027,25 @@ git-tree-sha1 = "7eb8cdaa6f0e8081616367c10b31b9d9b34bb02a" uuid = "0a4f8689-d25c-4efe-a92b-7142dfc1aa53" version = "0.6.7" +[[deps.MbedTLS]] +deps = ["Dates", "MbedTLS_jll", "MozillaCACerts_jll", "NetworkOptions", "Random", "Sockets"] +git-tree-sha1 = "8785729fa736197687541f7053f6d8ab7fc44f92" +uuid = "739be429-bea8-5141-9913-cc70e7f3736d" +version = "1.1.10" + +[[deps.MbedTLS_jll]] +deps = ["Artifacts", "JLLWrappers", "Libdl"] +git-tree-sha1 = "ff69a2b1330bcb730b9ac1ab7dd680176f5896b8" +uuid = "c8ffd9c3-330d-5841-b78e-0817d7145fa1" +version = "2.28.1010+0" + [[deps.MechanicalMaterialModels]] deps = ["ForwardDiff", "LinearAlgebra", "MaterialModelsBase", "Newton", "StaticArrays", "Tensors"] -git-tree-sha1 = "36f0bd95356e7af6b5d5009c241dbe5aedc7a14a" +git-tree-sha1 = "ddfce3820a135ba597d356bf4cd877d4962670f2" repo-rev = "main" repo-url = "https://github.com/KnutAM/MechanicalMaterialModels.jl.git" uuid = "b3282f9b-607f-4337-ab95-e5488ab5652c" -version = "0.2.1" +version = "0.3.0" [[deps.Missings]] deps = ["DataAPI"] @@ -992,7 +1065,7 @@ version = "0.3.4" [[deps.MozillaCACerts_jll]] uuid = "14a3606d-f60d-562e-9121-12d972cd8159" -version = "2025.5.20" +version = "2025.11.4" [[deps.NaNMath]] deps = ["OpenLibm_jll"] @@ -1018,7 +1091,7 @@ version = "1.3.0" [[deps.Newton]] deps = ["DiffResults", "ForwardDiff", "LinearAlgebra", "Preferences", "Printf", "StaticArrays", "Tensors"] -git-tree-sha1 = "f24d8c7a562b6fe883f1594ef2b643fcffc0587c" +git-tree-sha1 = "dc28c6c8c91eaf84925ab12aa2828fbc2165433d" repo-rev = "main" repo-url = "https://github.com/KnutAM/Newton.jl.git" uuid = "83aa5b51-0588-403c-85e4-434ec185aae7" @@ -1084,10 +1157,16 @@ git-tree-sha1 = "301412a644646fdc0ad67d0a87487466b491e53d" uuid = "9bd350c2-7e96-507f-8002-3f2e150b4e1b" version = "10.2.1+0" +[[deps.OpenSSL]] +deps = ["BitFlags", "Dates", "MozillaCACerts_jll", "NetworkOptions", "OpenSSL_jll", "Sockets"] +git-tree-sha1 = "1d1aaa7d449b58415f97d2839c318b70ffb525a0" +uuid = "4d8831e6-92b7-49fb-bdf8-b643e874388c" +version = "1.6.1" + [[deps.OpenSSL_jll]] deps = ["Artifacts", "Libdl"] uuid = "458c3c95-2e84-50aa-8efc-19380b2a3a95" -version = "3.5.1+0" +version = "3.5.4+0" [[deps.OpenSpecFun_jll]] deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "Libdl"] @@ -1160,7 +1239,7 @@ version = "0.44.2+0" [[deps.Pkg]] deps = ["Artifacts", "Dates", "Downloads", "FileWatching", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "Random", "SHA", "TOML", "Tar", "UUIDs", "p7zip_jll"] uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f" -version = "1.12.0" +version = "1.12.1" weakdeps = ["REPL"] [deps.Pkg.extensions] @@ -1282,6 +1361,16 @@ git-tree-sha1 = "62389eeff14780bfe55195b7204c0d8738436d64" uuid = "ae029012-a4dd-5104-9daa-d747884805df" version = "1.3.1" +[[deps.Revise]] +deps = ["CRC32c", "CodeTracking", "FileWatching", "JuliaInterpreter", "LibGit2", "LoweredCodeUtils", "OrderedCollections", "Preferences", "REPL", "UUIDs"] +git-tree-sha1 = "6098400ed73008c45f5f47b35ae114475436ad37" +uuid = "295af30f-e4ad-537b-8983-00126c2a3abe" +version = "3.16.2" +weakdeps = ["Distributed"] + + [deps.Revise.extensions] + DistributedExt = "Distributed" + [[deps.Rmath]] deps = ["Random", "Rmath_jll"] git-tree-sha1 = "5b3d50eb374cea306873b371d3f8d3915a018f0b" @@ -1342,6 +1431,11 @@ git-tree-sha1 = "d263a08ec505853a5ff1c1ebde2070419e3f28e9" uuid = "73760f76-fbc4-59ce-8f25-708e95d2df96" version = "0.4.0" +[[deps.SimpleBufferStream]] +git-tree-sha1 = "f305871d2f381d21527c770d4788c06c097c9bc1" +uuid = "777ac1f9-54b0-4bf8-805c-2214025038e7" +version = "1.2.0" + [[deps.SimpleTraits]] deps = ["InteractiveUtils", "MacroTools"] git-tree-sha1 = "be8eeac05ec97d379347584fa9fe2f5f76795bcb" @@ -1543,6 +1637,11 @@ git-tree-sha1 = "4d4ed7f294cda19382ff7de4c137d24d16adc89b" uuid = "981d1d27-644d-49a2-9326-4793e63143c3" version = "0.1.0" +[[deps.URIs]] +git-tree-sha1 = "3b0738bd7c5645641845da25cbd99800b8718689" +uuid = "5c2747f8-b7ea-4ff2-ba2e-563bfd36b1d4" +version = "1.6.2" + [[deps.UUIDs]] deps = ["Random", "SHA"] uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4" @@ -1732,9 +1831,9 @@ uuid = "1317d2d5-d96f-522e-a858-c73665f53c3e" version = "2022.0.0+1" [[deps.p7zip_jll]] -deps = ["Artifacts", "Libdl"] +deps = ["Artifacts", "CompilerSupportLibraries_jll", "Libdl"] uuid = "3f19e933-33d8-53b3-aaab-bd5110c3b7a0" -version = "17.5.0+2" +version = "17.7.0+0" [[deps.x264_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl"] diff --git a/docs/Project.toml b/docs/Project.toml index 4b38398c..a563dbb0 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -10,9 +10,11 @@ FerriteMeshParser = "0f8c756f-80dd-4a75-85c6-b0a5ab9d4620" ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210" IGA = "e7b8d123-e02a-40ba-ad18-d3943ed54f1c" Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" +LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" MaterialModelsBase = "af893363-701d-44dc-8b1e-d9a2c129bfc9" MechanicalMaterialModels = "b3282f9b-607f-4337-ab95-e5488ab5652c" Newton = "83aa5b51-0588-403c-85e4-434ec185aae7" +Revise = "295af30f-e4ad-537b-8983-00126c2a3abe" Tensors = "48a634ad-e948-5137-8d70-aa71f2a747f4" WriteVTK = "64499a7a-5c06-52f2-abe2-ccb03c286192" diff --git a/docs/generate.jl b/docs/generate.jl index 1ed3acff..49a779fb 100644 --- a/docs/generate.jl +++ b/docs/generate.jl @@ -2,8 +2,9 @@ import Literate function clean_output_files(dir) + isdir(dir) || return nothing num_deleted = 0 - cd(dir) do + cd(dir) do for file in readdir() if any(ext -> endswith(file, ext), (".vtu", ".pvd")) rm(file) @@ -34,8 +35,12 @@ function build_examples(jl_files; type) for example in jl_files input = abspath(joinpath(EXAMPLEDIR, example)) isfile(input) || throw(SystemError("$input not found")) - script = Literate.script(input, GENERATEDDIR) - code = strip(read(script, String)) + if !draft + script = Literate.script(input, GENERATEDDIR) + code = strip(read(script, String)) + else + code = "<< no script output when building as draft >>" + end # remove "hidden" lines which are not shown in the markdown line_ending_symbol = occursin(code, "\r\n") ? "\r\n" : "\n" @@ -43,7 +48,9 @@ function build_examples(jl_files; type) mdpost(str) = replace(str, "@__CODE__" => code_clean) Literate.markdown(input, GENERATEDDIR, postprocess = mdpost) - Literate.notebook(input, GENERATEDDIR, execute = is_ci) # Don't execute locally + if !draft + Literate.notebook(input, GENERATEDDIR, execute = is_ci) # Don't execute locally + end end clean_output_files(GENERATEDDIR) diff --git a/docs/liveserver.jl b/docs/liveserver.jl new file mode 100644 index 00000000..2534e3e0 --- /dev/null +++ b/docs/liveserver.jl @@ -0,0 +1,45 @@ +#!/usr/bin/env julia + +# Build the documentation and serve it locally, rebuilding whenever a source file +# changes. Pass `draft` to skip executing the tutorials and how-tos. + +if !(isempty(ARGS) || ARGS == ["draft"]) + throw(ArgumentError("usage: julia docs/liveserver.jl [draft]")) +end + +# Root of the repository +const repo_root = dirname(@__DIR__) + +# Make sure docs environment is active and instantiated +import Pkg +Pkg.activate(@__DIR__) +Pkg.instantiate() + +# Communicate with docs/make.jl that it should serve without deploying +push!(ARGS, "liveserver") + +# Run LiveServer.servedocs(...) +import LiveServer +LiveServer.servedocs(; + host = "0.0.0.0", + # Documentation root where make.jl and src/ are located + foldername = joinpath(repo_root, "docs"), + # Extra source folder to watch for changes + include_dirs = [ + # Watch the src folder so docstrings can be Revise'd + joinpath(repo_root, "src"), + ], + skip_dirs = [ + # Skip the folders where Literate.jl output is written. This is needed + # to avoid infinite loops where running make.jl updates watched files, + # which then triggers a new run of make.jl etc. + joinpath(repo_root, "docs/src/tutorials"), + joinpath(repo_root, "docs/src/howto"), + # Skip the folder with downloaded assets, see docs/download_assets.jl + joinpath(repo_root, "docs/src/assets"), + ], + include_files = [ + joinpath(repo_root, "docs/generate.jl"), + joinpath(repo_root, "docs/download_assets.jl"), + ], +) diff --git a/docs/make.jl b/docs/make.jl index 35260ec6..dc04fd6b 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,3 +1,11 @@ +const liveserver = "liveserver" in ARGS +const draft = "draft" in ARGS + +if liveserver + using Revise + Revise.revise() +end + using FerriteAssembly import FerriteAssembly: ExampleElements import MaterialModelsBase as MMB @@ -63,15 +71,21 @@ makedocs(; "Internals" => "internals.md", ] ], + draft=draft, + # When building as draft, no scripts or notebooks are generated by Literate, + # so the links to those in the generated markdown files are dangling. + warnonly = draft ? [:cross_references] : false, ) # Remove output files from build directory clean_output_files(joinpath(@__DIR__, "build", "tutorials")) clean_output_files(joinpath(@__DIR__, "build", "howto")) -deploydocs(; - repo="github.com/KnutAM/FerriteAssembly.jl.git", - devbranch="main", - push_preview=true, - versions = ["dev" => "dev", "stable" => "v^", "v#.#"] # dev first makes this default redirect -) +if !liveserver + deploydocs(; + repo="github.com/KnutAM/FerriteAssembly.jl.git", + devbranch="main", + push_preview=true, + versions = ["dev" => "dev", "stable" => "v^", "v#.#"] # dev first makes this default redirect + ) +end