nim doc .. fails when runnableExamples uses $ [devel] [regression]

[kaushalmodi]

While the recently merged PR #14439 fixed a lot of nim doc issues in my real world project, it has introduced a regression on devel where nim doc fails if a runnableExamples block has $ somewhere, like in the below example.

Example

# t.nim
proc foo*(): int =
  ## Some proc
  runnableExamples:
    echo "foo() = ", $foo()
  return

Run nim doc t.nim.

Current Output

strutils.nim(2693)       invalidFormatString
Error: unhandled exception: invalid format string [ValueError]

Expected Output

No error

Additional Information

• This is a severely breaking regression
• koch docs fails for the same reason
• Also nim doc lib/pure/strutils.nim (probably many more libs, as using $ in runnableExamples could be very common).
• https://github.com/nim-lang/Nim/runs/718075904?check_suite_focus=true#step:12:3426

By adding some debug info to the invalidFormatString (#14486) and the first % proc in strutils.nim like below:

proc `%` *(formatstr: string, a: openArray[string]): string {.noSideEffect,
  rtl, extern: "nsuFormatOpenArray".} =
  # ..
  ## * `strformat module<strformat.html>`_ for string interpolation and formatting
  debugEcho "formatstr = ", formatstr, ", a = ", a
  result = newStringOfCap(formatstr.len + a.len shl 4)
  addf(result, formatstr, a)

, on rebuilding nim and running nim doc t.nim (t.nim is the above minimal example), I get this debug info:

...
formatstr = $1, a = ["t"]
formatstr = autogenerated by docgen
loc: $1
rdoccmd: $2, a = ["/home/kmodi/sandbox/nim/bug_reports/t14485/t.nim(3, 3)", ""]
formatstr = <pre class="listing">, a = ["1", "langNim"]
formatstr = <span class="$1">$2</span>, a = ["Identifier", "echo"]
formatstr = <span class="$1">$2</span>, a = ["Whitespace", " "]
formatstr = <span class="$1">$2</span>, a = ["StringLit", "&quot;foo() = &quot;"]
formatstr = <span class="$1">$2</span>, a = ["Punctuation", ","]
formatstr = <span class="$1">$2</span>, a = ["Whitespace", " "]
formatstr = <span class="$1">$2</span>, a = ["Operator", "$"]
strutils.nim(2693)       invalidFormatString
Error: unhandled exception: invalid format string: <span class="Operator">$</span> [ValueError]

Error: unhandled exception: invalid format string: <span class="Operator">$</span> [ValueError]

$ nim -v
Nim Compiler Version 1.3.5 [Linux: amd64]
Compiled at 2020-05-28
Copyright (c) 2006-2020 by Andreas Rumpf

git hash: e013ebc91a22eeccc9546498994b0c561e438599
active boot switches: -d:release

/cc @timotheecour