Replace Documenter admonitions with quote blocks in notebook output (#259)

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

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

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"^# !!! (?<type>\w+)(?: \"(?<title>.+)\")?(?<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

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