Skip to content

Commit

Permalink
Merge pull request #96
Browse files Browse the repository at this point in the history 
Manually convert `Pluto` notebooks to `.md`
  • Loading branch information
@maltezfaria
maltezfaria authored Oct 10, 2024
2 parents 4ac8d85 + eab7d9e commit 25beb1e
Show file tree
Hide file tree
Showing 5 changed files with 541 additions and 649 deletions.
3 changes: 2 additions & 1 deletion docs/Project.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
209 changes: 116 additions & 93 deletions docs/make.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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",
Expand Down Expand Up @@ -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")

Expand All @@ -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,
Expand All @@ -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],
)
Expand All @@ -206,3 +227,5 @@ deploydocs(;
devbranch = "main",
push_preview = true,
)

# GLMakie.closeall()
Loading

0 comments on commit 25beb1e

Please sign in to comment.