I like `runnableExamples` and prefer it over the old `code-block` comments.
1.
If you dislike having syntax highlighting in examples, I'm sure the editor can
be configured to skip it for `runnableExamples` blocks.
2.
Is it really that bad? This looks fine to me:
proc f* =
## Start of doc
runnableExamples:
doAssert true
## continue
runnableExamples:
doAssert true
## end
Run
The generated docs looks like a mess because of multiple `Examples` headers,
but that could be fixed.
3.
I wish Araq had chosen markdown instead RST, but that ship has sailed.
