fix #10731 ; runnableExamples "-b:cpp --run:off": code works

[timotheecour]

• fixes runnableExamples that are only compiled #10731 with a general fix that allows passing arbitrary cmd to a given runnableExamples, as an argument rdoccmd to runnableExamples (bringing feature parity with the rst code block nim)

example

proc fun*() =
  ## some comment
  runnableExamples: discard # same as before
  runnableExamples "-d:foo -b:cpp":
    import std/compilesettings
    doAssert querySetting(backend) == "cpp"
  runnableExamples "-r:off": ## this one is only compiled
     import std/browsers
     openDefaultBrowser "https://forum.nim-lang.org/"

more examples

see tests in tests/nimdoc/trunnableexamples.nim

features

• plays well with --doccmd:cmd: --doccmd:cmd (if passed) is appended (not prepended) to rdoccmd so that we can override a test via cmdline; it'd be easy to add a prepend option if ever needed.

• runnableExamples are grouped by unique rdoccmd so that we maintain the "megatest" speed advantages introduced in 5fc78d8

• fixes runnableExamples that are only compiled #10731 as a special case: simply write:

runnableExamples "-r:off": ## this one is only compiled
   import std/browsers
   openDefaultBrowser "https://forum.nim-lang.org/"

workaround if false: was not good enough

it's uglier, eg:

import std/browsers
if false:
  openDefaultBrowser "https://forum.nim-lang.org/"

and doesn't work in many cases as a replacement for compile but not run:

• eg if some import would cause module level code to run which would fail (bc of some required dependency)
• or if it needs a dll that may not be available at runtime, which is a common problem, eg:

proc fun*() =
  # this would work fine with `runnableExamples: "-r:off"` and not require `if false:` hack
  runnableExamples:
    import sdl2, opengl
    if false: # this will still give a runtime failure in case sdl2 dll is not available at runtime
      discard sdl2.init(INIT_EVERYTHING)
      var window = createWindow("test", 100, 100, 640, 480, SDL_WINDOW_OPENGL or SDL_WINDOW_RESIZABLE)
      var context = window.glCreateContext()
      loadExtensions()
      var evt = sdl2.defaultEvent
      while true:
        while pollEvent(evt): break
        glClear(GL_COLOR_BUFFER_BIT or GL_DEPTH_BUFFER_BIT)
        delay 1_000
      destroy window

• furthermore it didn't handle at all the other use cases enabled by having custom command, eg -d:cpp --threads, or --compileOnly, etc.

bottom line: this makes it simple to have self contained examples in a single file, even if individual examples need different cmdline options

[timotheecour]

@Araq friendly ping on this (so I can avoid some workarounds in another PR)

[timotheecour]

thanks!