Improve Markdown code blocks & start moving docs to Markdown style (#19954)

- add additional parameters parsing (other implementations will just
  ignore them). E.g. if in RST we have:

  .. code:: nim
     :test: "nim c $1"

     ...

  then in Markdown that will be:

  ```nim test="nim c $1"
  ...
  ```

- implement Markdown interpretation of additional indentation which is
  less than 4 spaces (>=4 spaces is a code block but it's not
implemented yet). RST interpretes it as quoted block, for Markdown it's
just normal paragraphs.
- add separate `md2html` and `md2tex` commands. This is to separate
  Markdown behavior in cases when it diverges w.r.t. RST significantly —
most conspicously like in the case of additional indentation above, and
also currently the contradicting inline rule of Markdown is also turned
on only in `md2html` and `md2tex`. **Rationale:** mixing Markdown and
RST arbitrarily is a way to nowhere, we need to provide a way to fix the
particular behavior. Note that still all commands have **both** Markdown
and RST features **enabled**. In this PR `*.nim` files can be processed
only in Markdown mode, while `md2html` is for `*.md` files and
`rst2html` for `*.rst` files.
- rename `*.rst` files to `.*md` as our current default behavior is
  already Markdown-ish
- convert code blocks in `docgen.rst` to Markdown style as an example.
  Other code blocks will be converted in the follow-up PRs
- fix indentation inside Markdown code blocks — additional indentation
  is preserved there
- allow more than 3 backticks open/close blocks (tildas \~ are still not
  allowed to avoid conflict with RST adornment headings) see also
https://github.com/nim-lang/RFCs/issues/355
- better error messages
- (other) fix a bug that admonitions cannot be used in sandbox mode; fix
  annoying warning on line 2711

doc/backends.md

@@ -10,7 +10,8 @@
 .. no syntax highlighting here by default:
 
 .. contents::
-  "Heresy grows from idleness." -- Unknown.
+
+> "Heresy grows from idleness." -- Unknown.
 
 
 Introduction

doc/contributing.md

@@ -581,7 +581,7 @@ Code reviews
 
 
 
-.. include:: docstyle.rst
+.. include:: docstyle.md
 
 
 Evolving the stdlib

doc/docgen.md

@@ -35,14 +35,13 @@ Quick start
 
 Generate HTML documentation for a file:
 
-.. code:: cmd
-
+  ```cmd
   nim doc <filename>.nim
+  ```
 
 Generate HTML documentation for a whole project:
 
-.. code:: cmd
-
+  ```cmd
   # delete any htmldocs/*.idx file before starting
   nim doc --project --index:on --git.url:<url> --git.commit:<tag> --outdir:htmldocs <main_filename>.nim
   # this will generate html files, a theindex.html index, css and js under `htmldocs`
@@ -54,7 +53,7 @@ Generate HTML documentation for a whole project:
   # or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;
   # and likewise without `--project`.
   # Adding `-r` will open in a browser directly.
-
+  ```
 
 Documentation Comments
 ----------------------
@@ -120,8 +119,8 @@ Example of Nim file input
 The following examples will generate documentation for this sample
 *Nim* module, aptly named ``doc/docgen_sample.nim``:
 
-.. code:: nim
-   :file: docgen_sample.nim
+   ```nim file=docgen_sample.nim
+   ```
 
 All the below commands save their output to ``htmldocs`` directory relative to
 the directory of file;
@@ -137,9 +136,9 @@ optionally, an index file.
 
 The `doc`:option: command:
 
-.. code:: cmd
-
+  ```cmd
   nim doc docgen_sample.nim
+  ```
 
 Partial Output::
   ...
@@ -159,8 +158,7 @@ HTML -> PDF conversion).
 
 The `doc2tex`:option: command:
 
-.. code:: cmd
-
+  ```cmd
   nim doc2tex docgen_sample.nim
   cd htmldocs
   xelatex docgen_sample.tex
@@ -169,6 +167,7 @@ The `doc2tex`:option: command:
   # large documents) to get all labels generated.
   # That depends on this warning in the end of `xelatex` output:
   #   LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.
+  ```
 
 The output is ``docgen_sample.pdf``.
 
@@ -183,9 +182,9 @@ Note that this tool is built off of the `doc`:option: command
 
 The `jsondoc`:option: command:
 
-.. code:: cmd
-
+  ```cmd
   nim jsondoc docgen_sample.nim
+  ```
 
 Output::
   {
@@ -209,9 +208,9 @@ renamed to `jsondoc0`:option:.
 
 The `jsondoc0`:option: command:
 
-.. code:: cmd
-
+  ```cmd
   nim jsondoc0 docgen_sample.nim
+  ```
 
 Output::
   [
@@ -249,9 +248,9 @@ the anchor [*]_ of Nim symbol that corresponds to link text.
 
 If you have a constant:
 
-.. code:: Nim
-
+   ```Nim
    const pi* = 3.14
+   ```
 
 then it should be referenced in one of the 2 forms:
 
@@ -262,9 +261,9 @@ B. qualified (with symbol kind specification)::
 
 For routine kinds there are more options. Consider this definition:
 
-.. code:: Nim
-
+   ```Nim
    proc foo*(a: int, b: float): string
+   ```
 
 Generally following syntax is allowed for referencing `foo`:
 
@@ -352,11 +351,11 @@ recognized fine::
    (without parameter names, see form A.2 above).
    E.g. for this signature:
 
-   .. code:: Nim
-
+      ```Nim
       proc binarySearch*[T, K](a: openArray[T]; key: K;
                                cmp: proc (x: T; y: K): int {.closure.}): int
                                           ~~    ~~   ~~~~~
+      ```
 
    you cannot use names underlined by `~~` so it must be referenced with
    ``cmp: proc(T, K)``. Hence these forms are valid::
@@ -379,10 +378,10 @@ recognized fine::
 .. Note:: A bit special case is operators
    (as their signature is also defined with `\``):
 
-   .. code:: Nim
-
+      ```Nim
       func `$`(x: MyType): string
       func `[]`*[T](x: openArray[T]): T
+      ```
 
    A short form works without additional backticks::
 
@@ -412,9 +411,9 @@ Related Options
 Project switch
 --------------
 
-.. code:: cmd
-
+  ```cmd
   nim doc --project filename.nim
+  ```
 
 This will recursively generate documentation of all Nim modules imported
 into the input module that belong to the Nimble package that ``filename.nim``
@@ -425,9 +424,9 @@ also be generated.
 Index switch
 ------------
 
-.. code:: cmd
-
+  ```cmd
   nim doc --index:on filename.nim
+  ```
 
 This will generate an index of all the exported symbols in the input Nim
 module, and put it into a neighboring file with the extension of ``.idx``. The
@@ -443,9 +442,9 @@ file.
 See source switch
 -----------------
 
-.. code:: cmd
-
+  ```cmd
   nim doc --git.url:<url> filename.nim
+  ```
 
 With the `git.url`:option: switch the *See source* hyperlink will appear below each
 documented item in your source code pointing to the implementation of that
@@ -490,9 +489,9 @@ supports highlighting of a few other languages supported by the
 
 Usage:
 
-.. code:: cmd
-
+  ```cmd
   nim rst2html docgen.rst
+  ```
 
 Output::
   You're reading it!
@@ -528,7 +527,7 @@ HTML file, most browsers will go to the first one. To differentiate the rest,
 you will need to use the complex name. A complex name for a callable type is
 made up of several parts:
 
-    (**plain symbol**)(**.type**),(**first param**)?(**,param type**)\*
+  (**plain symbol**)(**.type**),(**first param**)?(**,param type**)\*
 
 The first thing to note is that all callable types have at least a comma, even
 if they don't have any parameters. If there are parameters, they are

doc/intern.md

@@ -10,7 +10,7 @@
 .. include:: rstcommon.rst
 .. contents::
 
-  "Abstraction is layering ignorance on top of reality." -- Richard Gabriel
+> "Abstraction is layering ignorance on top of reality." -- Richard Gabriel
 
 
 Directory structure
@@ -276,8 +276,8 @@ and `exitingDebugSection()`:nim:.
 #. Compile the temp compiler with `--debugger:native -d:nimDebugUtils`:option:
 #. Set your desired breakpoints or watchpoints.
 #. Configure your debugger:
-  * GDB: execute `source tools/compiler.gdb` at startup
-  * LLDB execute `command source tools/compiler.lldb` at startup
+   * GDB: execute `source tools/compiler.gdb` at startup
+   * LLDB execute `command source tools/compiler.lldb` at startup
 #. Use one of the scoping helpers like so:
 
 .. code-block:: nim

doc/manual.md

@@ -10,9 +10,9 @@ Nim Manual
 .. contents::
 
 
-  "Complexity" seems to be a lot like "energy": you can transfer it from the
-  end-user to one/some of the other players, but the total amount seems to remain
-  pretty much constant for a given task. -- Ran
+> "Complexity" seems to be a lot like "energy": you can transfer it from the
+> end-user to one/some of the other players, but the total amount seems to remain
+> pretty much constant for a given task. -- Ran
 
 
 About this document
@@ -4025,7 +4025,7 @@ In the standard library every name of a routine that returns a `var` type
 starts with the prefix `m` per convention.
 
 
-.. include:: manual/var_t_return.rst
+.. include:: manual/var_t_return.md
 
 Future directions
 ~~~~~~~~~~~~~~~~~

doc/manual_experimental.md

@@ -505,7 +505,7 @@ The compiler ensures that every code path initializes variables which contain
 non-nilable pointers. The details of this analysis are still to be specified
 here.
 
-.. include:: manual_experimental_strictnotnil.rst
+.. include:: manual_experimental_strictnotnil.md
 
 
 Aliasing restrictions in parameter passing

doc/mm.md

@@ -11,7 +11,7 @@ Nim's Memory Management
 ..
 
 
-  "The road to hell is paved with good intentions."
+> "The road to hell is paved with good intentions."
 
 
 Multi-paradigm Memory Management Strategies

doc/nimc.md

@@ -11,9 +11,9 @@
 
 ..
 
-  "Look at you, hacker. A pathetic creature of meat and bone, panting and
-  sweating as you run through my corridors. How can you challenge a perfect,
-  immortal machine?"
+> "Look at you, hacker. A pathetic creature of meat and bone, panting and
+> sweating as you run through my corridors. How can you challenge a perfect,
+> immortal machine?"
 
 
 Introduction

doc/nimgrep.md

@@ -54,7 +54,7 @@ All examples below use default PCRE Regex patterns:
     nimgrep --excludeDir:'^\.git$' --excludeDir:'^\.hg$' --excludeDir:'^\.svn$'
     # short: --ed:'^\.git$' --ed:'^\.hg$' --ed:'^\.svn$'
 
-+ To search only in paths containing the `tests` sub-directory recursively::
++ To search only in paths containing the `tests` sub-directory recursively:
 
   .. code:: cmd
     nimgrep --recursive --includeDir:'(^|/)tests($|/)'

doc/overview.md

@@ -5,5 +5,5 @@ Nim Documentation Overview
 :Author: Andreas Rumpf
 :Version: |nimversion|
 
-.. include:: docs.rst
+.. include:: docs.md
 

doc/tut2.md

@@ -13,7 +13,7 @@ Nim Tutorial (Part II)
 Introduction
 ============
 
-  "Repetition renders the ridiculous reasonable." -- Norman Wildberger
+> "Repetition renders the ridiculous reasonable." -- Norman Wildberger
 
 This document is a tutorial for the advanced constructs of the *Nim*
 programming language. **Note that this document is somewhat obsolete as the**

doc/tut3.md

@@ -13,7 +13,7 @@ Nim Tutorial (Part III)
 Introduction
 ============
 
-  "With Great Power Comes Great Responsibility." -- Spider Man's Uncle
+>  "With Great Power Comes Great Responsibility." -- Spider Man's Uncle
 
 This document is a tutorial about Nim's macro system.
 A macro is a function that is executed at compile-time and transforms