Better log messages for failed at-meta, at-docs,

at-autodocs, at-eval, at-example and at-setup blocks.
JuliaDocs · Jan 23, 2019 · bd606f3 · bd606f3
1 parent 46abe28
commit bd606f3
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 40 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,10 @@
 
 * ![Enhancement][badge-enhancement] Documentation is no longer deployed on Travis CI cron jobs. ([#917][github-917])
 
+* ![Enhancement][badge-enhancement] Log messages from failed `@meta`, `@docs`, `@autodocs`,
+  `@eval`, `@example` and `@setup` blocks now include information about the source location
+  of the block. ([#929][github-929])
+
 ## Version `v0.21.0`
 
 * ![Deprecation][badge-deprecation] ![Enhancement][badge-enhancement] The symbol values to the `format` argument of `makedocs` (`:html`, `:markdown`, `:latex`) have been deprecated in favor of the `Documenter.HTML`, `Markdown` and `LaTeX`
@@ -12,15 +16,15 @@
 
   **For upgrading:** If you don't specify `format` (i.e. you rely on the default) you don't have to do anything.
   Otherwise update calls to `makedocs` to use struct instances instead of symbols, e.g.
-  
+
   ```
   makedocs(
       format = :markdown
   )
   ```
-  
+
   should be changed to
-  
+
   ```
   using DocumenterMarkdown
   makedocs(
@@ -47,7 +51,7 @@
       ...
   )
   ```
-  
+
   _**Note:** It is technically possible to specify the same argument twice with different values by passing both variants. In that case the value to the deprecated `html_*` variant takes precedence._
 
 * ![Feature][badge-feature] Packages extending Documenter can now define subtypes of `Documenter.Plugin`,
@@ -177,6 +181,8 @@
 [github-898]: https://github.com/JuliaDocs/Documenter.jl/pull/898
 [github-905]: https://github.com/JuliaDocs/Documenter.jl/pull/905
 [github-907]: https://github.com/JuliaDocs/Documenter.jl/pull/907
+[github-917]: https://github.com/JuliaDocs/Documenter.jl/pull/917
+[github-929]: https://github.com/JuliaDocs/Documenter.jl/pull/929
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

diff --git a/src/DocTests.jl b/src/DocTests.jl
@@ -16,25 +16,6 @@ import Markdown, REPL
 # Julia code block testing.
 # -------------------------
 
-# escape characters that has a meaning in regex
-regex_escape(str) = sprint(escape_string, str, "\\^\$.|?*+()[{")
-
-# helper to display linerange for error printing
-function find_codeblock_in_file(code, file)
-    content = read(Base.find_source_file(file), String)
-    content = replace(content, "\r\n" => "\n")
-    # make a regex of the code that matches leading whitespace
-    rcode = "\\h*" * replace(regex_escape(code), "\\n" => "\\n\\h*")
-    blockidx = findfirst(Regex(rcode), content)
-    if blockidx !== nothing
-        startline = countlines(IOBuffer(content[1:prevind(content, first(blockidx))]))
-        endline = startline + countlines(IOBuffer(code)) + 1 # +1 to include the closing ```
-        return ":$(startline)-$(endline)"
-    else
-        return ""
-    end
-end
-
 """
 $(SIGNATURES)
 
@@ -78,7 +59,7 @@ function doctest(block::Markdown.Code, meta::Dict, doc::Documents.Document, page
             for kwarg in kwargs.args
                 if !(isa(kwarg, Expr) && kwarg.head === :(=) && isa(kwarg.args[1], Symbol))
                     file = meta[:CurrentFile]
-                    lines = find_codeblock_in_file(block.code, file)
+                    lines = Utilities.find_block_in_file(block.code, file)
                     @warn("""
                         invalid syntax for doctest keyword arguments in $(Utilities.locrepr(file, lines))
                         Use ```jldoctest name; key1 = value1, key2 = value2
@@ -112,7 +93,7 @@ function doctest(block::Markdown.Code, meta::Dict, doc::Documents.Document, page
         else
             push!(doc.internal.errors, :doctest)
             file = meta[:CurrentFile]
-            lines = find_codeblock_in_file(block.code, file)
+            lines = Utilities.find_block_in_file(block.code, file)
             @warn("""
                 invalid doctest block in $(Utilities.locrepr(file, lines))
                 Requires `julia> ` or `# output`
@@ -302,7 +283,7 @@ function report(result::Result, str, doc::Documents.Document)
     println(ioc, "=====[Test Error]", "="^30)
     println(ioc)
     printstyled(ioc, "> Location: ", result.file, color=:cyan)
-    printstyled(ioc, find_codeblock_in_file(result.block.code, result.file), color=:cyan)
+    printstyled(ioc, Utilities.find_block_in_file(result.block.code, result.file), color=:cyan)
     printstyled(ioc, "\n\n> Code block:\n", color=:cyan)
     println(ioc, "\n```$(result.block.language)")
     println(ioc, result.block.code)
@@ -336,7 +317,7 @@ function fix_doctest(result::Result, str, doc::Documents.Document)
     io = IOBuffer(sizehint = sizeof(content))
     # first look for the entire code block
     # make a regex of the code that matches leading whitespace
-    rcode = "(\\h*)" * replace(regex_escape(code), "\\n" => "\\n\\h*")
+    rcode = "(\\h*)" * replace(Utilities.regex_escape(code), "\\n" => "\\n\\h*")
     r = Regex(rcode)
     codeidx = findfirst(r, content)
     if codeidx === nothing
@@ -349,7 +330,7 @@ function fix_doctest(result::Result, str, doc::Documents.Document)
     write(io, content[1:prevind(content, first(codeidx))])
     # next look for the particular input string in the given code block
     # make a regex of the input that matches leading whitespace (for multiline input)
-    rinput = "\\h*" * replace(regex_escape(result.input), "\\n" => "\\n\\h*")
+    rinput = "\\h*" * replace(Utilities.regex_escape(result.input), "\\n" => "\\n\\h*")
     r = Regex(rinput)
     inputidx = findfirst(r, code)
     if inputidx === nothing

diff --git a/src/Expanders.jl b/src/Expanders.jl
@@ -237,13 +237,19 @@ end
 
 function Selectors.runner(::Type{MetaBlocks}, x, page, doc)
     meta = page.globals.meta
+    lines = Utilities.find_block_in_file(x.code, page.source)
     for (ex, str) in Utilities.parseblock(x.code, doc, page)
         if Utilities.isassign(ex)
             try
                 meta[ex.args[1]] = Core.eval(Main, ex.args[2])
             catch err
                 push!(doc.internal.errors, :meta_block)
-                @warn "failed to evaluate `$(strip(str))` in `@meta` block in $(Utilities.locrepr(page.source))" exception = err
+                @warn("""
+                    failed to evaluate `$(strip(str))` in `@meta` block in $(Utilities.locrepr(page.source, lines))
+                    ```$(x.language)
+                    $(x.code)
+                    ```
+                    """, exception = err)
             end
         end
     end
@@ -257,19 +263,31 @@ function Selectors.runner(::Type{DocsBlocks}, x, page, doc)
     failed = false
     nodes  = DocsNode[]
     curmod = get(page.globals.meta, :CurrentModule, Main)
+    lines = Utilities.find_block_in_file(x.code, page.source)
     for (ex, str) in Utilities.parseblock(x.code, doc, page)
         binding = try
             Documenter.DocSystem.binding(curmod, ex)
         catch err
             push!(doc.internal.errors, :docs_block)
-            @warn "unable to get the binding for '$(strip(str))' in $(Utilities.locrepr(page.source)) from expression '$(repr(ex))' in module $(curmod)" exception = err
+            @warn("""
+                unable to get the binding for '$(strip(str))' in `@docs` block in $(Utilities.locrepr(page.source, lines)) from expression '$(repr(ex))' in module $(curmod)
+                ```$(x.language)
+                $(x.code)
+                ```
+                """,
+                exception = err)
             failed = true
             continue
         end
         # Undefined `Bindings` get discarded.
         if !Documenter.DocSystem.iskeyword(binding) && !Documenter.DocSystem.defined(binding)
             push!(doc.internal.errors, :docs_block)
-            @warn "undefined binding '$(binding)' in $(Utilities.locrepr(page.source))."
+            @warn("""
+                undefined binding '$(binding)' in `@docs` block in $(Utilities.locrepr(page.source, lines))
+                ```$(x.language)
+                $(x.code)
+                ```
+                """)
             failed = true
             continue
         end
@@ -279,7 +297,12 @@ function Selectors.runner(::Type{DocsBlocks}, x, page, doc)
         # We can't include the same object more than once in a document.
         if haskey(doc.internal.objects, object)
             push!(doc.internal.errors, :docs_block)
-            @warn "duplicate docs found for '$(strip(str))' in $(Utilities.locrepr(page.source))."
+            @warn("""
+                duplicate docs found for '$(strip(str))' in `@docs` block in $(Utilities.locrepr(page.source, lines))
+                ```$(x.language)
+                $(x.code)
+                ```
+                """)
             failed = true
             continue
         end
@@ -295,7 +318,12 @@ function Selectors.runner(::Type{DocsBlocks}, x, page, doc)
         # Check that we aren't printing an empty docs list. Skip block when empty.
         if isempty(docs)
             push!(doc.internal.errors, :docs_block)
-            @warn "no docs found for '$(strip(str))' in $(Utilities.locrepr(page.source))."
+            @warn("""
+                no docs found for '$(strip(str))' in `@docs` block in $(Utilities.locrepr(page.source, lines))
+                ```$(x.language)
+                $(x.code)
+                ```
+                """)
             failed = true
             continue
         end
@@ -328,6 +356,7 @@ const AUTODOCS_DEFAULT_ORDER = [:module, :constant, :type, :function, :macro]
 function Selectors.runner(::Type{AutoDocsBlocks}, x, page, doc)
     curmod = get(page.globals.meta, :CurrentModule, Main)
     fields = Dict{Symbol, Any}()
+    lines = Utilities.find_block_in_file(x.code, pages.source)
     for (ex, str) in Utilities.parseblock(x.code, doc, page)
         if Utilities.isassign(ex)
             try
@@ -338,7 +367,12 @@ function Selectors.runner(::Type{AutoDocsBlocks}, x, page, doc)
                 end
             catch err
                 push!(doc.internal.errors, :autodocs_block)
-                @warn "failed to evaluate `$(strip(str))` in `@autodocs` block in $(Utilities.locrepr(page.source))" exception = err
+                @warn("""
+                    failed to evaluate `$(strip(str))` in `@autodocs` block in $(Utilities.locrepr(page.source, lines))
+                    ```$(x.language)
+                    $(x.code)
+                    ```
+                    """, exception = err)
             end
         end
     end
@@ -402,7 +436,12 @@ function Selectors.runner(::Type{AutoDocsBlocks}, x, page, doc)
         for (mod, path, category, object, isexported, docstr) in results
             if haskey(doc.internal.objects, object)
                 push!(doc.internal.errors, :autodocs_block)
-                @warn "duplicate docs found for '$(object.binding)' in $(Utilities.locrepr(page.source)).."
+                @warn("""
+                    duplicate docs found for '$(object.binding)' in $(Utilities.locrepr(page.source, lines))
+                    ```$(x.language)
+                    $(x.code)
+                    ```
+                    """)
                 continue
             end
             markdown = Markdown.MD(Documenter.DocSystem.parsedoc(docstr))
@@ -420,7 +459,12 @@ function Selectors.runner(::Type{AutoDocsBlocks}, x, page, doc)
         page.mapping[x] = DocsNodes(nodes)
     else
         push!(doc.internal.errors, :autodocs_block)
-        @warn "'@autodocs' missing 'Modules = ...' in $(Utilities.locrepr(page.source)).."
+        @warn("""
+            '@autodocs' missing 'Modules = ...' in $(Utilities.locrepr(page.source, lines))
+            ```$(x.language)
+            $(x.code)
+            ```
+            """
         page.mapping[x] = x
     end
 end
@@ -430,14 +474,20 @@ end
 
 function Selectors.runner(::Type{EvalBlocks}, x, page, doc)
     sandbox = Module(:EvalBlockSandbox)
+    lines = Utilities.find_block_in_file(x.code, page.source)
     cd(dirname(page.build)) do
         result = nothing
         for (ex, str) in Utilities.parseblock(x.code, doc, page)
             try
                 result = Core.eval(sandbox, ex)
             catch err
                 push!(doc.internal.errors, :eval_block)
-                @warn "failed to evaluate `@eval` block in $(Utilities.locrepr(page.source))" exception = err
+                @warn("""
+                    failed to evaluate `@eval` block in $(Utilities.locrepr(page.source))
+                    ```$(x.language)
+                    $(x.code)
+                    ```
+                    """, exception = err)
             end
         end
         page.mapping[x] = EvalNode(x, result)
@@ -470,6 +520,7 @@ function Selectors.runner(::Type{ExampleBlocks}, x, page, doc)
     name = match(r"^@example[ ]?(.*)$", first(split(x.language, ';', limit = 2)))[1]
     sym  = isempty(name) ? gensym("ex-") : Symbol("ex-", name)
     mod  = get!(() -> get_new_sandbox(sym), page.globals.meta, sym)
+    lines = Utilities.find_block_in_file(x.code, page.source)
 
     # "parse" keyword arguments to example (we only need to look for continued = true)
     continued = occursin(r"continued\s*=\s*true", x.language)
@@ -494,7 +545,12 @@ function Selectors.runner(::Type{ExampleBlocks}, x, page, doc)
             print(buffer, text)
             if !success
                 push!(doc.internal.errors, :example_block)
-                @warn "failed to run code block in $(Utilities.locrepr(page.source)):" value
+                @warn("""
+                    failed to run `@example` block in $(Utilities.locrepr(page.source, lines))
+                    ```$(x.language)
+                    $(x.code)
+                    ```
+                    """, value)
                 page.mapping[x] = x
                 return
             end
@@ -588,7 +644,12 @@ function Selectors.runner(::Type{SetupBlocks}, x, page, doc)
         Markdown.MD([])
     catch err
         push!(doc.internal.errors, :setup_block)
-        @warn "failed to run `@setup` block in $(Utilities.locrepr(page.source)):" exception=err
+        @warn("""
+            failed to run `@setup` block in $(Utilities.locrepr(page.source))
+            ```$(x.language)
+            $(x.code)
+            ```
+            """, exception=err)
         x
     end
     # ... and finally map the original code block to the newly generated ones.

diff --git a/src/Utilities/Utilities.jl b/src/Utilities/Utilities.jl
@@ -9,10 +9,29 @@ using DocStringExtensions
 import Markdown, LibGit2
 import Base64: stringmime
 
+# escape characters that has a meaning in regex
+regex_escape(str) = sprint(escape_string, str, "\\^\$.|?*+()[{")
+
+# helper to display linerange for error printing
+function find_block_in_file(code, file)
+    content = read(Base.find_source_file(file), String)
+    content = replace(content, "\r\n" => "\n")
+    # make a regex of the code that matches leading whitespace
+    rcode = "\\h*" * replace(regex_escape(code), "\\n" => "\\n\\h*")
+    blockidx = findfirst(Regex(rcode), content)
+    if blockidx !== nothing
+        startline = countlines(IOBuffer(content[1:prevind(content, first(blockidx))]))
+        endline = startline + countlines(IOBuffer(code)) + 1 # +1 to include the closing ```
+        return ":$(startline)-$(endline)"
+    else
+        return ""
+    end
+end
+
 # Pretty-printing locations
 function locrepr(file, line=nothing)
     str = Base.contractuser(file) # TODO: Maybe print this relative the doc-root??
-    line !== nothing && (str = str * ":$(line)")
+    line !== nothing && (str = str * "$(line)")
     return "`$(str)`"
 end