simplify doc creation (WIP)

.gitignore

@@ -9,6 +9,8 @@
 /test/Manifest.toml
 .vscode
 /docs/src/examples/generated/
+# ignore .md generated from notebooks
+/docs/src/pluto-notebooks/*.md 
 /sandbox/*
 /talks/*
 

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,8 +12,6 @@ using GLMakie
 using FMM2D
 using FMM3D
 
-cleanexamples()
-
 # from https://github.com/fonsp/Pluto.jl/pull/2471
 function generate_plaintext(
     notebook,
@@ -56,25 +54,22 @@ 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_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "pluto-notebooks")
+
+function generate_md(input; output = replace(input, ".jl" => ".md"))
     notebook = Pluto.load_notebook(input)
-    header = _ -> "<!-- Generated by Pluto $(Pluto.PLUTO_VERSION) -->"
     fname = basename(input)
+    function header(_)
+        return "[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)]($fname)"
+    end
     function codewrapper(cell, _)
         # 1. Strips begin/end block
         # 2. Reformats code using JuliaFormatter
         # 3. Wraps all code in same ```@example``` block for documenter
         code = strip(cell.code)
         if startswith(code, "begin") && endswith(code, "end")
-            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
+            # Remove "begin" and "end" and reformat block
+            code = strip(code[6:end-4])
             code = format_text(String(code))
         end
         return if cell.code_folded
@@ -102,43 +97,9 @@ 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)
@@ -154,26 +115,20 @@ end
 size_threshold_ignore = []
 notebooks = [
     "Toy example" => "toy_example.jl",
-    "Helmholtz scattering" => "helmholtz_scattering.jl",
-    "Poisson problem" => "poisson.jl",
+    # "Helmholtz scattering" => "helmholtz_scattering.jl",
+    # "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)
     file_out = generate_md(file_in)
-    push!(
-        notebook_examples,
-        name => joinpath("module_examples", replace(file, ".jl" => ".md")),
-    )
+    push!(notebook_examples, name => "pluto-notebooks/$(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)
+# ignore size threshold for notebooks
+size_threshold_ignore = last.(notebook_examples)
 
 makedocs(;
     modules = modules,
@@ -199,19 +154,11 @@ 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,
@@ -220,8 +167,6 @@ makedocs(;
     plugins = [bib, links],
 )
 
-cleanexamples()
-
 deploydocs(;
     repo = "github.com/IntegralEquations/Inti.jl",
     devbranch = "main",

docs/src/pluto-examples/toy_example.jl → docs/src/pluto-notebooks/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
+(i) markdown files passed to Documenter.jl, and (ii) pluto notebook files
+downloadable from the example's page.
 """
 
 # ╔═╡ 00000000-0000-0000-0000-000000000001