From d33107254e18669c5bbaed619e868c3a3f04987d Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Wed, 16 Oct 2024 13:49:08 +0200 Subject: [PATCH] Replace Documenter admonitions with quote blocks in notebook output (#259) --- CHANGELOG.md | 22 ++++++++++++++++++ docs/src/documenter.md | 18 ++++++++++++++ src/Literate.jl | 19 +++++++++++++++ test/runtests.jl | 53 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 112 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5080254..5f96655 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 false`) execution errors are re-thrown by Literate (as before). If `continue_on_error = true` is set the error is used as the block result and execution continues with following blocks. ([#201], [#257]) + - Literate now replaces Documenter-style admonitions when generating notebook output + ([#259]). Concretely, + ``` + # !!! note + # A note. + + # !!! warn "Warning title text" + # A warning. + ``` + is replaced with + ``` + # > **Note** + # > + # > A note. + + # > **Warning title text** + # > + # > A warning. + ``` ## [v2.19.1] - 2024-09-13 ### Fixed @@ -319,6 +338,7 @@ https://discourse.julialang.org/t/ann-literate-jl/10651 for release announcement [#197]: https://github.com/fredrikekre/Literate.jl/issues/197 [#199]: https://github.com/fredrikekre/Literate.jl/issues/199 [#200]: https://github.com/fredrikekre/Literate.jl/issues/200 +[#201]: https://github.com/fredrikekre/Literate.jl/issues/201 [#204]: https://github.com/fredrikekre/Literate.jl/issues/204 [#205]: https://github.com/fredrikekre/Literate.jl/issues/205 [#219]: https://github.com/fredrikekre/Literate.jl/issues/219 @@ -335,6 +355,8 @@ https://discourse.julialang.org/t/ann-literate-jl/10651 for release announcement [#248]: https://github.com/fredrikekre/Literate.jl/issues/248 [#251]: https://github.com/fredrikekre/Literate.jl/issues/251 [#252]: https://github.com/fredrikekre/Literate.jl/issues/252 +[#257]: https://github.com/fredrikekre/Literate.jl/issues/257 +[#259]: https://github.com/fredrikekre/Literate.jl/issues/259 [0872a96]: https://github.com/fredrikekre/Literate.jl/commit/0872a96 [0f9e836]: https://github.com/fredrikekre/Literate.jl/commit/0f9e836 [1d02868]: https://github.com/fredrikekre/Literate.jl/commit/1d02868 diff --git a/docs/src/documenter.md b/docs/src/documenter.md index 5598423..3479ce2 100644 --- a/docs/src/documenter.md +++ b/docs/src/documenter.md @@ -45,6 +45,24 @@ if we set `documenter = true`: \int f dx $$ ``` +- Documenter style admonitions + ``` + !!! note + An interesting note. + + !!! warning "Warning title text" + An important warning. + ``` + are replaced with notebook compatible quote blocks + ``` + > **Note** + > + > An interesting note. + + > **Warning title text** + > + > An important warning. + ``` - Whereas Documenter requires HTML blocks to be escaped ```` ```@raw html diff --git a/src/Literate.jl b/src/Literate.jl index e861238..5003bc9 100644 --- a/src/Literate.jl +++ b/src/Literate.jl @@ -227,6 +227,25 @@ function replace_default(content, sym; push!(repls, r"\[([^]]+?)\]\(@extref\)"s => s"\1") # [foo](@extref) => foo push!(repls, r"\[([^]]+?)\]\(@extref .*?\)"s => s"\1") # [foo](@extref bar) => foo push!(repls, r"\[([^]]+?)\]\(@id .*?\)"s => s"\1") # [foo](@id bar) => foo + # Convert Documenter admonitions to markdown quotes + r = r"^# !!! (?\w+)(?: \"(?.+)\")?(?<lines>(\v^# .*$)+)"m + adm_to_quote = function(s) + m = match(r, s)::RegexMatch + io = IOBuffer() + print(io, "# > **") + if (title = m[:title]; title !== nothing) + print(io, title) + else + type = uppercasefirst(String(m[:type])) + print(io, type) + end + print(io, "**\n# >") + for l in eachline(IOBuffer(m[:lines]); keep = true) + print(io, replace(l, r"^# " => "# > ")) + end + return String(take!(io)) + end + push!(repls, r => adm_to_quote) end # do the replacements diff --git a/test/runtests.jl b/test/runtests.jl index 971501b..af30d8e 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -1475,6 +1475,59 @@ end end end end +@testset "admonitions" begin + src = + """ + # !!! note + # This is a note on one line. + # + # !!! warn "Warning title text" + # This is a warning + # on multiple lines. + """ + mktempdir(@__DIR__) do sandbox + inputfile = joinpath(sandbox, "input.jl") + write(inputfile, src) + # Literate.markdown + Literate.markdown(inputfile, sandbox; documenter = false) + output = read(joinpath(sandbox, "input.md"), String) + expected = """ + > **Note** + > + > This is a note on one line. + + > **Warning title text** + > + > This is a warning + > on multiple lines. + """ + @test occursin(expected, output) + # Literate.notebook + Literate.notebook(inputfile, sandbox) + output = read(joinpath(sandbox, "input.ipynb"), String) + @test occursin("> **Note**\\n", output) + @test occursin(">\\n", output) + @test occursin("> This is a note on one line.", output) + @test occursin("> **Warning title text**\\n", output) + @test occursin("> This is a warning\\n", output) + @test occursin("> on multiple lines.", output) + # Literate.script + Literate.script(inputfile, sandbox; name = "output", keep_comments = true) + output = read(joinpath(sandbox, "output.jl"), String) + expected = """ + # > **Note** + # > + # > This is a note on one line. + # + # > **Warning title text** + # > + # > This is a warning + # > on multiple lines. + """ + @test occursin(expected, output) + end +end + @testset "Configuration" begin; Base.CoreLogging.with_logger(Base.CoreLogging.NullLogger()) do mktempdir(@__DIR__) do sandbox cd(sandbox) do