Manually convert Pluto notebooks to .md

docs/Project.toml

@@ -11,11 +11,12 @@ GSL = "92c85e6c-cbff-5e0c-80f7-495c94daaecd"
 Gmsh = "705231aa-382f-11e9-3f0c-b7cb4346fdeb"
 HMatrices = "8646bddf-ab1c-4fa7-9c51-ba187d647618"
 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"
-PlutoStaticHTML = "359b1769-a58e-495b-9770-312e911026ad"
 PlutoUI = "7f904dfe-b85e-4ff6-b463-dae2292396a8"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"

docs/make.jl

@@ -2,7 +2,8 @@ using Inti
 using Documenter
 using DocumenterCitations
 using DocumenterInterLinks
-using ExampleJuggler, Literate, PlutoStaticHTML, PlutoSliderServer
+using ExampleJuggler, Literate, PlutoSliderServer
+using Pluto, JuliaFormatter
 # packages needed for extensions
 using Gmsh
 using HMatrices
@@ -11,65 +12,85 @@ using GLMakie
 using FMM2D
 using FMM3D
 
-# Function to remove "begin #hide" and "end #hide" from a markdown file
-function formatting_pluto(input_file::String, output_file::String)
-    # Read the contents of the file
-    file_content = read(input_file, String)
-
-    # Replace the "begin #hide" and "end #hide" with an empty string
-    cleaned_content = replace(file_content, r"\b(end #hide)\b" => "")
-    cleaned_content = replace(cleaned_content, r"\b(end; #hide)\b" => "")
-    cleaned_content = replace(cleaned_content, r"\b(end;#hide)\b" => "")
-    cleaned_content = replace(cleaned_content, r"begin #hide\s*" => "")
-    cleaned_content = replace(cleaned_content, r"let #hide\s*" => "")
-
-    # Write the modified content back to a new file
-    open(output_file, "w") do f
-        return write(f, cleaned_content)
-    end
-end
-
-# Function to format the terminal output for the documentation
-function formatting_terminal_output(input_file::String, output_file::String)
-    # Read the contents of the file
-    file_content = read(input_file, String)
-
-    # Replace the plutouiterminal in the md file by plutouiterminal with padding and background color
-    cleaned_content = replace(
-        file_content,
-        r"\bplutouiterminal\b" => "plutouiterminal\" style=\"padding: 10px; background-color: white;",
-    )
-
-    # replace info macro (to keep?? or not use the macro)
-    cleaned_content = replace(
-        cleaned_content,
-        r"�\[36m�\[1m\[ �\[22m�\[39m�\[36m�\[1mInfo: �\[22m�\[39m" => "[ Info: ",
-    )
+cleanexamples()
 
-    # Write the modified content back to a new file
-    open(output_file, "w") do f
-        return write(f, cleaned_content)
+# from https://github.com/fonsp/Pluto.jl/pull/2471
+function generate_plaintext(
+    notebook,
+    strmacrotrim::Union{String,Nothing} = nothing;
+    header::Function = _ -> nothing,
+    footer::Function = _ -> nothing,
+    textcomment::Function = identity,
+    codewrapper::Function,
+)
+    cell_strings = String[]
+    header_content = header(notebook)
+    isnothing(header_content) || push!(cell_strings, header_content)
+    for cell_id in notebook.cell_order
+        cell = notebook.cells_dict[cell_id]
+        scode = strip(cell.code)
+        (raw, ltrim, rtrim) = if isnothing(strmacrotrim)
+            false, 0, 0
+        elseif startswith(scode, string(strmacrotrim, '"'^3))
+            true, length(strmacrotrim) + 3, 3
+        elseif startswith(scode, string(strmacrotrim, '"'))
+            true, length(strmacrotrim) + 1, 1
+        else
+            false, 0, 0
+        end
+        push!(
+            cell_strings,
+            if raw
+                text = strip(
+                    scode[nextind(scode, 1, ltrim):prevind(scode, end, rtrim)],
+                    ['\n'],
+                )
+                ifelse(Pluto.is_disabled(cell), textcomment, identity)(text)
+            else
+                codewrapper(cell, Pluto.is_disabled(cell))
+            end,
+        )
     end
+    footer_content = footer(notebook)
+    isnothing(footer_content) || push!(cell_strings, footer_content)
+    return join(cell_strings, "\n\n")
 end
 
-# Function to format the note sections in the markdown file
-function formatting_note_tip_md(input_file::String, output_file::String)
-    # Read the contents of the file
-    file_content = read(input_file, String)
-
-    cleaned_content =
-        replace(file_content, r"\badmonition is-note\b" => "admonition is-info")
-    cleaned_content =
-        replace(cleaned_content, r"\badmonition is-tip\b" => "admonition is-success")
-
-    # Write the modified content back to a new file
-    open(output_file, "w") do f
-        return write(f, cleaned_content)
+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) -->"
+    fname = basename(input)
+    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
+            code = format_text(String(code))
+        end
+        return if cell.code_folded
+            string("```@setup $fname\n", code, "\n```")
+        else
+            string("```@example $fname\n", code, "\n```")
+        end
     end
+    textcomment(text) = string("<!-- ", text, " -->")
+    str = generate_plaintext(notebook, "md"; header, codewrapper, textcomment)
+    open(output, "w") do io
+        return write(io, str)
+    end
+    return output
 end
 
-cleanexamples()
-
 links = InterLinks(
     "Meshes" => "https://juliageometry.github.io/MeshesDocs/dev/objects.inv",
     "HMatrices" => "https://integralequations.github.io/HMatrices.jl/stable/objects.inv",
@@ -97,26 +118,26 @@ 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 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
+# 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")
 
@@ -137,22 +158,22 @@ notebooks = [
     "Poisson problem" => "poisson.jl",
 ]
 
-# Generate markdown versions of the notebooks for documentation using PlutoStaticHTML.jl
-notebook_examples = @docplutonotebooks(notebook_dir, notebooks, iframe = false)
-size_threshold_ignore = last.(notebook_examples)
+mkdir(joinpath(Inti.PROJECT_ROOT, "docs", "src", "module_examples"))
 
-# Formatting the markdown files
+notebook_examples = Pair{String,String}[]
 for notebook in notebooks
-    get_md_files = replace(notebook[2], ".jl" => ".md")
-    file =
-        joinpath(Inti.PROJECT_ROOT, "docs", "src", "plutostatichtml_examples", get_md_files)
-    formatting_pluto(file, file)
-    formatting_terminal_output(file, file)
-    formatting_note_tip_md(file, file)
+    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")),
+    )
 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)
+# notebook_examples_html = @docplutonotebooks(notebook_dir, notebooks, iframe = true)
 
 makedocs(;
     modules = modules,
@@ -178,23 +199,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",
-        ],
+        # "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 = ON_CI ? false : Documenter.except(:linkcheck_remotes),
+    warnonly = Documenter.except(:linkcheck_remotes), # ON_CI ? false : Documenter.except(:linkcheck_remotes),
     # warnonly = true,
     pagesonly = true,
     checkdocs = :none,
-    clean=false,
+    clean = false,
     draft,
     plugins = [bib, links],
 )
@@ -206,3 +227,5 @@ deploydocs(;
     devbranch = "main",
     push_preview = true,
 )
+
+# GLMakie.closeall()