Wrap method name in Code in missing doc admonition

CHANGELOG.md

@@ -9,7 +9,7 @@
   of the block. ([#929][github-929])
 
 * ![Enhancement][badge-enhancement] Docstrings from `@docs`-blocks are now included in the
-  rendered docs even if some part(s) of the block failed. ([#928][github-928])
+  rendered docs even if some part(s) of the block failed. ([#928][github-928], [#935][github-935])
 
 ## Version `v0.21.1`
 
@@ -199,6 +199,7 @@
 [github-927]: https://github.com/JuliaDocs/Documenter.jl/pull/927
 [github-928]: https://github.com/JuliaDocs/Documenter.jl/pull/928
 [github-929]: https://github.com/JuliaDocs/Documenter.jl/pull/929
+[github-935]: https://github.com/JuliaDocs/Documenter.jl/pull/935
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

src/Expanders.jl

@@ -265,7 +265,7 @@ function Selectors.runner(::Type{DocsBlocks}, x, page, doc)
     lines = Utilities.find_block_in_file(x.code, page.source)
     for (ex, str) in Utilities.parseblock(x.code, doc, page)
         admonition = Markdown.Admonition("warning", "Missing docstring.",
-            Any[Markdown.Paragraph(["Missing docstring for `$(strip(str))`. Check Documenter's build log for details."])])
+            Utilities.mdparse("Missing docstring for `$(strip(str))`. Check Documenter's build log for details.", mode=:blocks))
         binding = try
             Documenter.DocSystem.binding(curmod, ex)
         catch err

src/Utilities/Utilities.jl

@@ -597,6 +597,44 @@ Checks whether `url` is an absolute URL (as opposed to a relative one).
 isabsurl(url) = occursin(ABSURL_REGEX, url)
 const ABSURL_REGEX = r"^[[:alpha:]+-.]+://"
 
+"""
+    mdparse(s::AbstractString; mode=:single)
+
+Parses the given string as Markdown using `Markdown.parse`, but strips away the surrounding
+layers, such as the outermost `Markdown.MD`. What exactly is returned depends on the `mode`
+keyword.
+
+The `mode` keyword argument can be one of the following:
+
+* `:single` (default) -- returns a single block-level object (e.g. `Markdown.Paragraph` or
+  `Markdown.Admonition`) and errors if the string parses into multiple blocks.
+* `:blocks` -- the function returns a `Vector{Any}` of Markdown blocks.
+* `:span` -- Returns a `Vector{Any}` of span-level items, stripping away the outer block.
+  This requires the string to parse into a single `Markdown.Paragraph`, the contents of
+  which gets returned.
+"""
+function mdparse(s::AbstractString; mode=:single)
+    mode in [:single, :blocks, :span] || throw(ArgumentError("Invalid mode keyword $(mode)"))
+    md = Markdown.parse(s)
+    if mode == :blocks
+        md.content
+    elseif length(md.content) == 0
+        # case where s == "". We'll just return an empty string / paragraph.
+        (mode == :single) ? Markdown.Paragraph(Any[""]) : Any[""]
+    elseif (mode == :single || mode == :span) && length(md.content) > 1
+        @error "mode == :$(mode) requires the Markdown string to parse into a single block" s md.content
+        throw(ArgumentError("Unsuitable string for mode=:$(mode)"))
+    else
+        @assert length(md.content) == 1
+        @assert mode == :span || mode == :single
+        if mode == :span && !isa(md.content[1], Markdown.Paragraph)
+            @error "mode == :$(mode) requires the Markdown string to parse into a Markdown.Paragraph" s md.content
+            throw(ArgumentError("Unsuitable string for mode=:$(mode)"))
+        end
+        (mode == :single) ? md.content[1] : md.content[1].content
+    end
+end
+
 include("DOM.jl")
 include("MDFlatten.jl")
 include("TextDiff.jl")

test/utilities.jl

@@ -4,6 +4,7 @@ using Test
 import Base64: stringmime
 
 import Documenter
+import Markdown
 
 module UnitTests
     module SubModule end
@@ -218,6 +219,39 @@ end
             end
         end
     end
+
+    @testset "mdparse" begin
+        mdparse = Documenter.Utilities.mdparse
+
+        @test_throws ArgumentError mdparse("", mode=:foo)
+
+        mdparse("") isa Markdown.Paragraph
+        @test mdparse("foo bar") isa Markdown.Paragraph
+        let md = mdparse("", mode=:span)
+            @test md isa Vector{Any}
+            @test length(md) == 1
+        end
+        let md = mdparse("", mode=:blocks)
+            @test md isa Vector{Any}
+            @test length(md) == 0
+        end
+
+        @test mdparse("!!! adm"; mode=:single) isa Markdown.Admonition
+        let md = mdparse("!!! adm", mode=:blocks)
+            @test md isa Vector{Any}
+            @test length(md) == 1
+        end
+        let md = mdparse("x\n\ny", mode=:blocks)
+            @test md isa Vector{Any}
+            @test length(md) == 2
+        end
+
+        @info "Expected error output:"
+        @test_throws ArgumentError mdparse("!!! adm", mode=:span)
+        @test_throws ArgumentError mdparse("x\n\ny")
+        @test_throws ArgumentError mdparse("x\n\ny", mode=:span)
+        @info ".. end of expected error output."
+    end
 end
 
 end