change some code-blocks to runnableExamples and correct some errors in docs (#15900)

* original docs are wrong
* fix pathnorm
* Update lib/pure/pathnorm.nim

Co-authored-by: Juan Carlos <juancarlospaco@gmail.com>
(cherry picked from commit ef2677f5f3)

lib/pure/httpcore.nim

@@ -262,11 +262,8 @@ func contains*(methods: set[HttpMethod], x: string): bool =
 
 func `$`*(code: HttpCode): string =
   ## Converts the specified ``HttpCode`` into a HTTP status.
-  ##
-  ## For example:
-  ##
-  ##   .. code-block:: nim
-  ##       doAssert($Http404 == "404 Not Found")
+  runnableExamples:
+    doAssert($Http404 == "404 Not Found")
   case code.int
   of 100: "100 Continue"
   of 101: "101 Switching Protocols"

lib/pure/json.nim

@@ -519,9 +519,10 @@ proc `{}`*(node: JsonNode, keys: varargs[string]): JsonNode =
   ## This proc can be used to create tree structures on the
   ## fly (sometimes called `autovivification`:idx:):
   ##
-  ## .. code-block:: nim
-  ##   myjson{"parent", "child", "grandchild"} = newJInt(1)
-  ##
+  runnableExamples:
+    var myjson = %* {"parent": {"child": {"grandchild": 1}}}
+    doAssert myjson{"parent", "child", "grandchild"} == newJInt(1)
+
   result = node
   for key in keys:
     if isNil(result) or result.kind != JObject:
@@ -1258,32 +1259,30 @@ when defined(nimFixedForwardGeneric):
     ##   * Sets in object variants are not supported.
     ##   * Not nil annotations are not supported.
     ##
-    ## Example:
-    ##
-    ## .. code-block:: Nim
-    ##     let jsonNode = parseJson("""
-    ##        {
-    ##          "person": {
-    ##            "name": "Nimmer",
-    ##            "age": 21
-    ##          },
-    ##          "list": [1, 2, 3, 4]
-    ##        }
-    ##     """)
-    ##
-    ##     type
-    ##       Person = object
-    ##         name: string
-    ##         age: int
-    ##
-    ##       Data = object
-    ##         person: Person
-    ##         list: seq[int]
-    ##
-    ##     var data = to(jsonNode, Data)
-    ##     doAssert data.person.name == "Nimmer"
-    ##     doAssert data.person.age == 21
-    ##     doAssert data.list == @[1, 2, 3, 4]
+    runnableExamples:
+      let jsonNode = parseJson("""
+        {
+          "person": {
+            "name": "Nimmer",
+            "age": 21
+          },
+          "list": [1, 2, 3, 4]
+        }
+      """)
+
+      type
+        Person = object
+          name: string
+          age: int
+
+        Data = object
+          person: Person
+          list: seq[int]
+
+      var data = to(jsonNode, Data)
+      doAssert data.person.name == "Nimmer"
+      doAssert data.person.age == 21
+      doAssert data.list == @[1, 2, 3, 4]
 
     var jsonPath = ""
     initFromJson(result, node, jsonPath)

lib/pure/math.nim

@@ -839,10 +839,10 @@ when not defined(js):
     ## float value) equals ``m * 2**n``. frexp stores n in `exponent` and returns
     ## m.
     ##
-    ## .. code-block:: nim
-    ##  var x: int
-    ##  echo frexp(5.0, x) # 0.625
-    ##  echo x # 3
+    runnableExamples:
+      var x: int
+      doAssert frexp(5.0, x) == 0.625
+      doAssert x == 3
     var exp: int32
     result = c_frexp(x, exp)
     exponent = exp
@@ -906,9 +906,9 @@ proc splitDecimal*[T: float32|float64](x: T): tuple[intpart: T, floatpart: T] =
   ## Both parts have the same sign as ``x``.  Analogous to the ``modf``
   ## function in C.
   ##
-  ## .. code-block:: nim
-  ##  echo splitDecimal(5.25)  # (intpart: 5.0, floatpart: 0.25)
-  ##  echo splitDecimal(-2.73) # (intpart: -2.0, floatpart: -0.73)
+  runnableExamples:
+    doAssert splitDecimal(5.25) == (intpart: 5.0, floatpart: 0.25)
+    doAssert splitDecimal(-2.73) == (intpart: -2.0, floatpart: -0.73)
   var
     absolute: T
   absolute = abs(x)
@@ -926,8 +926,8 @@ proc degToRad*[T: float32|float64](d: T): T {.inline.} =
   ## See also:
   ## * `radToDeg proc <#radToDeg,T>`_
   ##
-  ## .. code-block:: nim
-  ##  echo degToRad(180.0) # 3.141592653589793
+  runnableExamples:
+    doAssert degToRad(180.0) == 3.141592653589793
   result = T(d) * RadPerDeg
 
 proc radToDeg*[T: float32|float64](d: T): T {.inline.} =
@@ -936,8 +936,8 @@ proc radToDeg*[T: float32|float64](d: T): T {.inline.} =
   ## See also:
   ## * `degToRad proc <#degToRad,T>`_
   ##
-  ## .. code-block:: nim
-  ##  echo degToRad(2 * PI) # 360.0
+  runnableExamples:
+    doAssert radToDeg(2 * PI) == 360.0
   result = T(d) / RadPerDeg
 
 proc sgn*[T: SomeNumber](x: T): int {.inline.} =
@@ -948,10 +948,10 @@ proc sgn*[T: SomeNumber](x: T): int {.inline.} =
   ## * `1` for positive numbers and ``Inf``,
   ## * `0` for positive zero, negative zero and ``NaN``
   ##
-  ## .. code-block:: nim
-  ##  echo sgn(5)    # 1
-  ##  echo sgn(0)    # 0
-  ##  echo sgn(-4.1) # -1
+  runnableExamples:
+    doAssert sgn(5) == 1
+    doAssert sgn(0) == 0
+    doAssert sgn(-4.1) == -1
   ord(T(0) < x) - ord(x < T(0))
 
 {.pop.}

lib/pure/pathnorm.nim

@@ -100,15 +100,13 @@ proc addNormalizePath*(x: string; result: var string; state: var int;
   if result == "" and x != "": result = "."
 
 proc normalizePath*(path: string; dirSep = DirSep): string =
-  ## Example:
-  ##
-  ## .. code-block:: nim
-  ##   assert normalizePath("./foo//bar/../baz") == "foo/baz"
-  ##
-  ##
+  runnableExamples:
+    when defined(posix):
+      doAssert normalizePath("./foo//bar/../baz") == "foo/baz"
+
   ## - Turns multiple slashes into single slashes.
-  ## - Resolves '/foo/../bar' to '/bar'.
-  ## - Removes './' from the path (but "foo/.." becomes ".")
+  ## - Resolves `'/foo/../bar'` to `'/bar'`.
+  ## - Removes `'./'` from the path, but `"foo/.."` becomes `"."`.
   result = newStringOfCap(path.len)
   var state = 0
   addNormalizePath(path, result, state, dirSep)