trying to simplify Pluto to Documenter conversion (WIP)

.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

@@ -12,6 +12,11 @@ using GLMakie
 using FMM2D
 using FMM3D
 
+const ON_CI = get(ENV, "CI", "false") == "true"
+
+draft = true # 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(
     notebook,
@@ -54,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, ".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
@@ -92,47 +97,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)
@@ -148,21 +112,16 @@ 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)
+    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)
 
@@ -193,14 +152,6 @@ 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",
@@ -214,8 +165,6 @@ makedocs(;
     plugins = [bib, links],
 )
 
-cleanexamples()
-
 deploydocs(;
     repo = "github.com/IntegralEquations/Inti.jl",
     devbranch = "main",

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,15 +9,13 @@ 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