Tweak the Pluto to Documenter pipeline

.github/workflows/documentation.yml

@@ -18,6 +18,7 @@ jobs:
       - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
+      - uses: julia-actions/cache@v2
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy without coverage

.gitignore

@@ -8,7 +8,7 @@
 /docs/build/
 /test/Manifest.toml
 .vscode
-/docs/src/examples/generated/
+/docs/src/pluto-examples/*.md 
 /sandbox/*
 /talks/*
 

docs/Project.toml

@@ -2,21 +2,20 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
-ExampleJuggler = "3bbe58f8-ed81-4c4e-a134-03e85fcf4a1a"
 FMM2D = "2d63477d-9690-4b75-bcc1-c3461d43fecc"
 FMM3D = "1e13804c-f9b7-11ea-0ef0-29f3b1745df8"
 FMMLIB2D = "1a804d9e-d798-534b-a6a9-4525c36f0718"
 GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 GSL = "92c85e6c-cbff-5e0c-80f7-495c94daaecd"
 Gmsh = "705231aa-382f-11e9-3f0c-b7cb4346fdeb"
 HMatrices = "8646bddf-ab1c-4fa7-9c51-ba187d647618"
+Inti = "fb74042b-437e-4c5b-88cf-d4e2beb394d5"
 IterativeSolvers = "42fd0dbc-a981-5370-80f2-aaf504508153"
 JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"
 LinearMaps = "7a12625a-238d-50fd-b39a-03d52299707e"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Meshes = "eacbb407-ea5a-433e-ab97-5258b1ca43fa"
 Pluto = "c3e4b0f8-55cb-11ea-2926-15256bba5781"
-PlutoSliderServer = "2fc8631c-6f24-4c5b-bca7-cbb509c42db4"
 PlutoUI = "7f904dfe-b85e-4ff6-b463-dae2292396a8"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"

docs/make.jl

@@ -2,8 +2,8 @@ using Inti
 using Documenter
 using DocumenterCitations
 using DocumenterInterLinks
-using ExampleJuggler, Literate, PlutoSliderServer
-using Pluto, JuliaFormatter
+using Pluto
+using JuliaFormatter
 # packages needed for extensions
 using Gmsh
 using HMatrices
@@ -12,7 +12,10 @@ using GLMakie
 using FMM2D
 using FMM3D
 
-cleanexamples()
+const ON_CI = get(ENV, "CI", "false") == "true"
+
+draft = false # build docs without running code. Useful for quick local testing
+ON_CI && (draft = false) # always full build on CI
 
 # from https://github.com/fonsp/Pluto.jl/pull/2471
 function generate_plaintext(
@@ -56,13 +59,13 @@ function generate_plaintext(
     return join(cell_strings, "\n\n")
 end
 
-function generate_md(
-    input;
-    output = replace(replace(input, r"..$" => "md"), "pluto-examples" => "module_examples"),
-)
-    notebook = Pluto.load_notebook(input)
-    header = _ -> "<!-- Generated by Pluto $(Pluto.PLUTO_VERSION) -->"
+function generate_md(input; output = replace(input, r"\.jl$" => ".md"))
     fname = basename(input)
+    notebook = Pluto.load_notebook(input)
+    header =
+        _ ->
+            "[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)]($fname)"
+
     function codewrapper(cell, _)
         # 1. Strips begin/end block
         # 2. Reformats code using JuliaFormatter
@@ -72,10 +75,6 @@ function generate_md(
             code = strip(code[6:end-4])  # Remove "begin" and "end" and strip spaces
             # reformat code using JuliaFormatter
             code = format_text(String(code))
-        elseif startswith(code, "let") && endswith(code, "end")
-            code = strip(code[4:end-4])  # Remove "let" and "end" and strip spaces
-            # reformat code using JuliaFormatter
-            code = format_text(String(code))
         end
         return if cell.code_folded
             string("```@setup $fname\n", code, "\n```")
@@ -85,6 +84,7 @@ function generate_md(
     end
     textcomment(text) = string("<!-- ", text, " -->")
     str = generate_plaintext(notebook, "md"; header, codewrapper, textcomment)
+
     open(output, "w") do io
         return write(io, str)
     end
@@ -98,47 +98,6 @@ links = InterLinks(
 
 bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"); style = :numeric)
 
-draft = false
-
-const ON_CI = get(ENV, "CI", "false") == "true"
-const GIT_HEAD = chomp(read(`git rev-parse HEAD`, String))
-const SETUP = """
-#nb import Pkg
-#nb Pkg.activate(temp=true)
-#nb Pkg.add(url="https://github.com/IntegralEquations/Inti.jl", rev="$GIT_HEAD")
-#nb foreach(Pkg.add, DEPENDENCIES)
-"""
-
-ON_CI && (draft = false) # always full build on CI
-
-function insert_setup(content)
-    ON_CI || return content
-    return replace(content, "#nb ## __NOTEBOOK_SETUP__" => SETUP)
-end
-
-## TO REMOVE if we decide to use Pluto Notebooks to generate documentation
-# Generate examples using Literate
-# const examples_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "examples")
-const notebook_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "pluto-examples")
-# const generated_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "examples", "generated")
-# const examples = ["toy_example.jl", "helmholtz_scattering.jl"]
-# for t in examples
-#     println("\n*** Generating $t example")
-#     @time begin
-#         src = joinpath(examples_dir, t)
-#         Literate.markdown(src, generated_dir; mdstrings = true)
-#         # if draft, skip creation of notebooks
-#         Literate.notebook(
-#             src,
-#             generated_dir;
-#             mdstrings = true,
-#             preprocess = insert_setup,
-#             # execute = ON_CI,
-#             execute = false,
-#         )
-#     end
-# end
-
 println("\n*** Generating documentation")
 
 DocMeta.setdocmeta!(Inti, :DocTestSetup, :(using Inti); recursive = true)
@@ -158,23 +117,15 @@ notebooks = [
     "Poisson problem" => "poisson.jl",
 ]
 
-mkdir(joinpath(Inti.PROJECT_ROOT, "docs", "src", "module_examples"))
-
 notebook_examples = Pair{String,String}[]
 for notebook in notebooks
-    name, file = notebook
-    file_in = joinpath(notebook_dir, file)
+    title, fname = notebook
+    file_in = joinpath(@__DIR__, "src", "pluto-examples", fname)
     file_out = generate_md(file_in)
-    push!(
-        notebook_examples,
-        name => joinpath("module_examples", replace(file, ".jl" => ".md")),
-    )
+    push!(notebook_examples, title => joinpath("pluto-examples", basename(file_out)))
 end
 size_threshold_ignore = last.(notebook_examples)
 
-# Generate HTML versions of the notebooks using PlutoSliderServer.jl
-# notebook_examples_html = @docplutonotebooks(notebook_dir, notebooks, iframe = true)
-
 makedocs(;
     modules = modules,
     repo = "",
@@ -199,33 +150,23 @@ makedocs(;
             "tutorials/correction_methods.md",
             "tutorials/solvers.md",
         ],
-        # "Examples" => [
-        #     "examples/generated/toy_example.md",
-        #     "examples/generated/helmholtz_scattering.md",
-        #     "examples/poisson.md",
-        #     # "examples/generated/lippmann_schwinger.md",
-        #     # "examples/generated/poisson.md",
-        #     # "examples/generated/stokes_drag.md",
-        # ],
         "Notebooks" => notebook_examples,
         "References" => "references.md",
         "Docstrings" => "docstrings.md",
     ],
-    warnonly = Documenter.except(:linkcheck_remotes), # ON_CI ? false : Documenter.except(:linkcheck_remotes),
+    warnonly = ON_CI ? false : Documenter.except(:linkcheck_remotes),
     # warnonly = true,
     pagesonly = true,
     checkdocs = :none,
-    clean = false,
+    clean = true,
     draft,
     plugins = [bib, links],
 )
 
-cleanexamples()
-
 deploydocs(;
     repo = "github.com/IntegralEquations/Inti.jl",
     devbranch = "main",
     push_preview = true,
 )
 
-# GLMakie.closeall()
+GLMakie.closeall()

docs/src/pluto-examples/helmholtz_scattering.jl

@@ -28,8 +28,6 @@ end
 # ╔═╡ a6c80f87-ff47-496f-8925-1275b58b02e1
 md"""
 # Helmholtz scattering
-
-[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)](../../pluto_examples/helmholtz_scattering.jl)$\hspace{5pt}$[![nbviewer](https://img.shields.io/badge/show-nbviewer-blue.svg)](../../pluto_examples/helmholtz_scattering.html)
 """
 
 # ╔═╡ 1715d794-a33d-4faf-953c-b706a9ceea23

docs/src/pluto-examples/poisson.jl

@@ -33,8 +33,6 @@ end
 # ╔═╡ aca57c74-d084-40e7-9760-edf988a64915
 md"""
 # Poisson Problem
-
-[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)](../../pluto_examples/poisson.jl)$\hspace{5pt}$[![nbviewer](https://img.shields.io/badge/show-nbviewer-blue.svg)](../../pluto_examples/poisson.html)
 """
 
 # ╔═╡ 4160cbc1-3e98-4919-a8b5-bfbc65077b53

docs/src/pluto-examples/toy_example.jl

@@ -1,5 +1,5 @@
 ### A Pluto.jl notebook ###
-# v0.19.46
+# v0.19.47
 
 using Markdown
 using InteractiveUtils
@@ -9,20 +9,21 @@ using Inti
 
 # ╔═╡ 3f5a1750-7cd7-11ef-2223-4f3db029916b
 begin
-	import Pkg as _Pkg
-	haskey(ENV, "PLUTO_PROJECT") && _Pkg.activate(ENV["PLUTO_PROJECT"])
-end ;
+    import Pkg as _Pkg
+    haskey(ENV, "PLUTO_PROJECT") && _Pkg.activate(ENV["PLUTO_PROJECT"])
+end;
 
 # ╔═╡ 854743f0-8556-4495-ba16-52514c85922a
 md"""
 # Toy example
-
-[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)](../../pluto_examples/toy_example.jl)$\hspace{5pt}$[![nbviewer](https://img.shields.io/badge/show-nbviewer-blue.svg)](../../pluto_examples/toy_example.html)
 """
 
 # ╔═╡ 09c0bfc0-1c65-4fad-b486-b6a61ca580e8
 md"""
-All examples in Inti.jl are autogenerated by executing the `make.jl` script in the `docs` folder. The workflow uses [Pluto.jl](https://plutojl.org), [JuliaFormatter](https://domluna.github.io/JuliaFormatter.jl/stable/), and [PlutoSliderServer.jl](https://github.com/JuliaPluto/PlutoSliderServer.jl) (via the intermediate of [ExampleJuggler.jl](https://github.com/j-fu/ExampleJuggler.jl)) to generate (i) markdown files passed to Documenter.jl, and (ii) pluto notebook files downloadable from the example's page.
+All examples in Inti.jl are autogenerated by executing the `make.jl` script in
+the `docs` folder. The workflow uses [Pluto.jl](https://plutojl.org) to generate
+markdown files passed to Documenter.jl. The original pluto notebook files
+are downloadable from the example's page.
 """
 
 # ╔═╡ 00000000-0000-0000-0000-000000000001

src/kernels.jl

@@ -5,7 +5,7 @@ const PREDEFINED_OPERATORS = ["Laplace", "Helmholtz", "Stokes", "Yukawa"]
 
 A kernel functions `K` with the signature `K(target,source)::T`.
 
-See also: [`GenericKernel`](@ref), [`SingleLayerKernel`](@ref),
+See also: [`SingleLayerKernel`](@ref),
 [`DoubleLayerKernel`](@ref), [`AdjointDoubleLayerKernel`](@ref),
 [`HyperSingularKernel`](@ref)
 """