Merge pull request #91 from gregoirepourtier/doc_Pluto

Generates documentation examples from Pluto notebooks

docs/Project.toml

@@ -2,17 +2,22 @@
 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"
 LinearMaps = "7a12625a-238d-50fd-b39a-03d52299707e"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Meshes = "eacbb407-ea5a-433e-ab97-5258b1ca43fa"
+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"
 WriteVTK = "64499a7a-5c06-52f2-abe2-ccb03c286192"

docs/make.jl

@@ -2,7 +2,7 @@ using Inti
 using Documenter
 using DocumenterCitations
 using DocumenterInterLinks
-using Literate
+using ExampleJuggler, Literate, PlutoStaticHTML, PlutoSliderServer
 # packages needed for extensions
 using Gmsh
 using HMatrices
@@ -11,6 +11,65 @@ 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: ",
+    )
+
+    # 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 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)
+    end
+end
+
+cleanexamples()
+
 links = InterLinks(
     "Meshes" => "https://juliageometry.github.io/MeshesDocs/dev/objects.inv",
     "HMatrices" => "https://integralequations.github.io/HMatrices.jl/stable/objects.inv",
@@ -36,8 +95,10 @@ function insert_setup(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
@@ -69,6 +130,30 @@ for extension in
     push!(modules, ext)
 end
 
+size_threshold_ignore = []
+notebooks = [
+    "Toy example" => "toy_example.jl",
+    "Helmholtz scattering" => "helmholtz_scattering.jl",
+    "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)
+
+# Formatting the markdown files
+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)
+end
+
+# Generate HTML versions of the notebooks using PlutoSliderServer.jl
+notebook_examples_html = @docplutonotebooks(notebook_dir, notebooks, iframe = true)
+
 makedocs(;
     modules = modules,
     repo = "",
@@ -79,6 +164,8 @@ makedocs(;
         size_threshold = 2 * 2^20, # 2 MiB
         size_threshold_warn = 1 * 2^20, # 1 MiB
         sidebar_sitename = false,
+        mathengine = MathJax3(),
+        size_threshold_ignore,
     ),
     pages = [
         "Home" => "index.md",
@@ -99,17 +186,21 @@ makedocs(;
             # "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 = true,
     pagesonly = true,
     checkdocs = :none,
+    clean=false,
     draft,
     plugins = [bib, links],
 )
 
+cleanexamples()
+
 deploydocs(;
     repo = "github.com/IntegralEquations/Inti.jl",
     devbranch = "main",