Add LiveServer setup with optional draft mode for building docs

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`.
 

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

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"
 

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,16 +35,22 @@ 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"
         code_clean = join(filter(x->!endswith(x,"#hide"),split(code, r"\n|\r\n")), line_ending_symbol)
 
         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)