Report file names in which "Unexpected Julia interpolation" occurred

[aaruni96]

Fixes #2752

Depends on #2792

[aaruni96]

In my testing, when I introduce a deliberate error in Oscar's experimental/FTheoryTools/docs/src/literature.md, I get the output

ERROR:     Unexpected Julia interpolation in the Markdown. This probably means that you have an
    unbalanced or un-escaped $ in the text.

    To write the dollar sign, escape it with `\$`

    Navnode is currently set to Experimental/FTheoryTools/literature.md, with parent NavNode(nothing, "F-Theory Tools", NavNode(nothing, ...)), and we
    got given the value:

    `$` which is of type `Symbol`

[asinghvi17]

Navnode is currently set to Experimental/FTheoryTools/literature.md,

could probably be better rephrased to

This is on the page Experimental/FTheoryTools/literature.md,

[fingolfin]

@aaruni96 PR #2803 is now merged. Can you please resolve the conflicts in CHANGELOG.md and then try this:

Suggested change

	This is on the page $(locrepr(dctx.navnode.page)), with parent $(dctx.navnode.parent), and we
	were given the value:
	This is in file $(locrepr(dctx)), and we were given the value:

[fingolfin]

The missing docs before src is to be expected, given that Oscar's docs/make.jl does this:

  cd(joinpath(oscardir, "docs")) do
    ...
    makedocs(;
    ...
  end

and the file names/paths we print are relative to the current working directory.

I am not sure why Oscar does that, it would be nice if we could get rid of it, but that's for another day.

[aaruni96]

and then try this:

This doesn't work, complains about wrong data types. I tried monkey patching a few things hoping its a trivial error, but I couldn't make any headway (just more and different errors).

The error I get is

ERROR: FieldError: type Documenter.HTMLWriter.HTMLContext has no field `page`, available fields: `doc`, `settings`, `scripts`, `documenter_js`, `themeswap_js`, `warner_js`, `search_index`, `search_index_js`, `search_navnode`, `atexample_warnings`
Stacktrace:
  [1] getproperty
    @ ./Base_compiler.jl:54 [inlined]
  [2] locrepr(dctx::Documenter.HTMLWriter.DCtx, lines::Nothing)
    @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:715
  [3] locrepr(dctx::Documenter.HTMLWriter.DCtx)
    @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:713
  [4] domify(dctx::Documenter.HTMLWriter.DCtx, ::MarkdownAST.Node{Nothing}, e::MarkdownAST.JuliaValue)
    @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:2446
  [5] domify(dctx::Documenter.HTMLWriter.DCtx, node::MarkdownAST.Node{Nothing})
    @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:1813
  [6] #domify##2
    @ ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:1816 [inlined]
...

[fingolfin]

Argh. Seems my previous PR did not have enough coverage to reveal that I messed up... Try applying this patch in addition:

diff --git a/src/html/HTMLWriter.jl b/src/html/HTMLWriter.jl
index 6868a874c..2803165fd 100644
--- a/src/html/HTMLWriter.jl
+++ b/src/html/HTMLWriter.jl
@@ -710,9 +710,7 @@ struct DCtx
 end
 
 function Documenter.locrepr(dctx::DCtx, lines = nothing)
-    doc = dctx.ctx.doc
-    page = dctx.navnode.page
-    return Documenter.locrepr(dctx.ctx.doc, dctx.ctx.page, lines)
+    return Documenter.locrepr(dctx.ctx.doc, dctx.navnode.page, lines)
 end
 
 function SearchRecord(ctx::HTMLContext, navnode; fragment = "", title = nothing, category = "page", text = "")

[aaruni96]

Without trying it now, relying on my memory of attempting something like this during my "monkey patching", I expect this to not work because dctx.navnode.page is a string, but locrepr expects something of type ::Page.

[fingolfin]

No, my patch is patching the locrepr method I added earlier today. It had a merge conflict which I resolved incorrectly.

[aaruni96]

After applying your patch, I still get the error I predicted :

ERROR: FieldError: type String has no field `source`; String has no fields at all.
Stacktrace:
  [1] getproperty
    @ ./Base_compiler.jl:54 [inlined]
  [2] locrepr(doc::Documenter.Document, page::String, lines::Nothing)
    @ Documenter ~/Programs/git/GitHub/Documenter.jl/src/utilities/utilities.jl:84
  [3] locrepr(dctx::Documenter.HTMLWriter.DCtx, lines::Nothing)
    @ Documenter.HTMLWriter ~/Programs/git/GitHub/Documenter.jl/src/html/HTMLWriter.jl:713

The locrepr method in utilities.jl doesn't specify needing the second argument as a ::Page, but assumes it, and tries accessing the field source.

[fingolfin]

I've applied the adjustments and fixed the errors. At least in local tests it works fine (it's a bit hard to tell exactly without #2804 merged, and without the dedicated tests this really deserves, but we'll get there)

[aaruni96]

In my testing, I get

ERROR:     Unexpected Julia interpolation in the Markdown. This probably means that you have an
    unbalanced or un-escaped $ in the text.

    To write the dollar sign, escape it with `\$`

    This is in file src/Experimental/FTheoryTools/literature.md, and we were given the value:

    `$` which is of type `Symbol`

With your earlier comment,

The missing docs before src is to be expected

I think, this is ready to be merged.

[fingolfin]

Taking a step back and thinking about this again, I wonder: perhaps we should simply perform this check earlier. Namely when we ingest docstrings (at which point we have precise location information), we could run a quick check on what we got and look for this issue, and report it then. This way, not only do we get better location info, but also we don't have to implement this for every writer again.

Thoughts @mortenpi ?

(To be clear, I'd still want to merge this PR, as it is an improvement now)

[fingolfin]

I resolved conflicts, adjusted to the new "warning tests", then used the opportunity to in fact further adjust those warning messages to be properly indented.