try new doc setup (WIP)

IntegralEquations · Oct 14, 2024 · c2e5cde · c2e5cde
1 parent 894beb5
commit c2e5cde
Show file tree

Hide file tree

Showing 5 changed files with 87 additions and 89 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -12,79 +12,9 @@ using GLMakie
 using FMM2D
 using FMM3D
 
-# 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
-
-notebook_dir = joinpath(Inti.PROJECT_ROOT, "docs", "src", "pluto-notebooks")
+const ON_CI = get(ENV, "CI", "false") == "true"
 
-function generate_md(input; output = replace(input, ".jl" => ".md"))
-    notebook = Pluto.load_notebook(input)
-    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")
-            # Remove "begin" and "end" and reformat block
-            code = strip(code[6:end-4])
-            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
+include(joinpath(Inti.PROJECT_ROOT, "docs", "src", "docutils.jl"))
 
 links = InterLinks(
     "Meshes" => "https://juliageometry.github.io/MeshesDocs/dev/objects.inv",
@@ -93,12 +23,8 @@ 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))
-
-ON_CI && (draft = false) # always full build on CI
+draft = true
+# ON_CI && (draft = false) # always full build on CI
 
 println("\n*** Generating documentation")
 
@@ -115,13 +41,14 @@ 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",
 ]
 
 notebook_examples = Pair{String,String}[]
 for notebook in notebooks
     name, file = notebook
+    notebook_dir = joinpath(@__DIR__, "src", "pluto-notebooks")
     file_in = joinpath(notebook_dir, file)
     file_out = generate_md(file_in)
     push!(notebook_examples, name => "pluto-notebooks/$(basename(file_out))")
@@ -158,8 +85,8 @@ makedocs(;
         "References" => "references.md",
         "Docstrings" => "docstrings.md",
     ],
-    warnonly = ON_CI ? false : Documenter.except(:linkcheck_remotes),
-    # warnonly = true,
+    # warnonly = ON_CI ? false : Documenter.except(:linkcheck_remotes),
+    warnonly = true,
     pagesonly = true,
     checkdocs = :none,
     clean = false,
@@ -173,4 +100,4 @@ deploydocs(;
     push_preview = true,
 )
 
-# GLMakie.closeall()
+GLMakie.closeall()
diff --git a/docs/src/docutils.jl b/docs/src/docutils.jl
@@ -0,0 +1,74 @@
+using Pluto
+using JuliaFormatter
+
+# 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 generate_md(input; output = replace(input, ".jl" => ".md"))
+    notebook = Pluto.load_notebook(input)
+    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")
+            # Remove "begin" and "end" and reformat block
+            code = strip(code[6:end-4])
+            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
diff --git a/docs/src/pluto-notebooks/helmholtz_scattering.jl b/docs/src/pluto-notebooks/helmholtz_scattering.jl
@@ -1,5 +1,5 @@
 ### A Pluto.jl notebook ###
-# v0.19.46
+# v0.19.47
 
 using Markdown
 using InteractiveUtils

diff --git a/docs/src/pluto-notebooks/poisson.jl b/docs/src/pluto-notebooks/poisson.jl
@@ -1,5 +1,5 @@
 ### A Pluto.jl notebook ###
-# v0.19.46
+# v0.19.47
 
 using Markdown
 using InteractiveUtils
@@ -33,8 +33,6 @@ end
 # ╔═╡ aca57c74-d084-40e7-9760-edf988a64915
 md"""
 # Poisson Problem
-
-[![Pluto notebook](https://img.shields.io/badge/download-Pluto_notebook-blue)](../../pluto_examples/poisson.jl)$\hspace{5pt}$[![nbviewer](https://img.shields.io/badge/show-nbviewer-blue.svg)](../../pluto_examples/poisson.html)
 """
 
 # ╔═╡ 4160cbc1-3e98-4919-a8b5-bfbc65077b53

diff --git a/src/kernels.jl b/src/kernels.jl
@@ -5,8 +5,7 @@ const PREDEFINED_OPERATORS = ["Laplace", "Helmholtz", "Stokes", "Yukawa"]
 
 A kernel functions `K` with the signature `K(target,source)::T`.
 
-See also: [`GenericKernel`](@ref), [`SingleLayerKernel`](@ref),
-[`DoubleLayerKernel`](@ref), [`AdjointDoubleLayerKernel`](@ref),
+See also: [`SingleLayerKernel`](@ref), [`DoubleLayerKernel`](@ref), [`AdjointDoubleLayerKernel`](@ref),
 [`HyperSingularKernel`](@ref)
 """
 abstract type AbstractKernel{T} end