From c2e5cde391471223f19cc67ed39443fc069c526b Mon Sep 17 00:00:00 2001 From: "Luiz M. Faria" Date: Sun, 13 Oct 2024 20:43:19 +0200 Subject: [PATCH] try new doc setup (WIP) --- docs/make.jl | 93 ++----------------- docs/src/docutils.jl | 74 +++++++++++++++ .../pluto-notebooks/helmholtz_scattering.jl | 2 +- docs/src/pluto-notebooks/poisson.jl | 4 +- src/kernels.jl | 3 +- 5 files changed, 87 insertions(+), 89 deletions(-) create mode 100644 docs/src/docutils.jl diff --git a/docs/make.jl b/docs/make.jl index 3e4b5620..803ff24b 100644 --- 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("") - 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 new file mode 100644 index 00000000..4352d7f7 --- /dev/null +++ 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("") + 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 index 2207f88a..2337fb68 100644 --- 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 index e1d3222e..99109f3f 100644 --- 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 index 74e432cb..2968d442 100644 --- 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