Types
@@ -229,7 +232,27 @@
cmp: proc (x: T; y: K): int {.closure.}): int" href="#binarySearch,openArray[T],K,proc(T,K)">binarySearch proc.
Ref. type like G and type G and G[T] and type G*[T].
Group ref. with capital letters works: fN11 or fn11
-Ref. [] is the same as proc `[]`(G[T]) because there are no overloads. The full form: proc `[]`*[T](x: G[T]): TRef. []= aka `[]=`(G[T], int, T).Ref. $ aka proc $ or proc `$`.Ref. $(a: ref SomeType).Ref. foo_bar aka iterator foo_bar_.Ref. fn[T; U,V: SomeFloat]().Ref. 'big or func `'big` or `'big`(string).
+Ref. [] is the same as proc `[]`(G[T]) because there are no overloads. The full form: proc `[]`*[T](x: G[T]): TRef. []= aka `[]=`(G[T], int, T).Ref. $ aka proc $ or proc `$`.Ref. $(a: ref SomeType).Ref. foo_bar aka iterator foo_bar_.Ref. fn[T; U,V: SomeFloat]().Ref. 'big or func `'big` or `'big`(string).
+Now repeat all the auto links of above in Pandoc Markdown Syntax.
+Ref group fn2 or specific function like fn2() or fn2( int ) or fn2(int, float).
+Ref generics like this: binarySearch or binarySearch(openArray[T], K, proc (T, K)) or proc binarySearch(openArray[T], K, proc (T, K)) or in different style: proc binarysearch(openarray[T], K, proc(T, K)). Can be combined with export symbols and type parameters: binarysearch*[T, K](openArray[T], K, proc (T, K)). With spaces binary search.
+Note that proc can be used in postfix form: binarySearch proc.
+Ref. type like G and type G and G[T] and type G*[T].
+Group ref. with capital letters works: fN11 or fn11
+Ref. `[]` is the same as proc `[]`(G[T]) because there are no overloads. The full form: proc `[]`*[T](x: G[T]): T Ref. `[]=` aka `[]=`(G[T], int, T). Ref. $ aka proc $ or proc `$`. Ref. $(a: ref SomeType). Ref. foo_bar aka iterator foo_bar_. Ref. fn[T; U,V: SomeFloat](). Ref. 'big or func `'big` or `'big`(string).
+
+Pandoc Markdown has synax for changing text of links: Ref. this proc or another symbol.
+
+Let us repeat auto links from symbols section below:
+There is also variant f(G[string]). See also f(G[int]).
+
diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.idx b/nimdoc/testproject/expected/subdir/subdir_b/utils.idx
index 5c8fee5277..007101b374 100644
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.idx
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.idx
@@ -36,3 +36,6 @@ Next header subdir/subdir_b/utils.html#this-is-now-a-header-next-header Next h
And so on subdir/subdir_b/utils.html#next-header-and-so-on And so on
More headers subdir/subdir_b/utils.html#more-headers More headers
Up to level 6 subdir/subdir_b/utils.html#more-headers-up-to-level-6 Up to level 6
+Pandoc Markdown subdir/subdir_b/utils.html#pandoc-markdown Pandoc Markdown
+Link name syntax subdir/subdir_b/utils.html#pandoc-markdown-link-name-syntax Link name syntax
+Symbols documentation subdir/subdir_b/utils.html#pandoc-markdown-symbols-documentation Symbols documentation
diff --git a/nimdoc/testproject/subdir/subdir_b/utils.nim b/nimdoc/testproject/subdir/subdir_b/utils.nim
index e201a3d388..f535d7f743 100644
--- a/nimdoc/testproject/subdir/subdir_b/utils.nim
+++ b/nimdoc/testproject/subdir/subdir_b/utils.nim
@@ -79,7 +79,9 @@ func fn9*(a: int): int = 42 ## comment
func fn10*(a: int): int = a ## comment
# Note capital letter N will be handled correctly in
-# group references like fN11_ or fn11_:
+# group references like fN11_ or fn11_
+# (or [fN11] or [fn11] in Markdown Syntax):
+
func fN11*() = discard
func fN11*(x: int) = discard
@@ -160,3 +162,52 @@ proc fn*[T; U, V: SomeFloat]() = discard
## Ref. `'big`_ or `func \`'big\``_ or `\`'big\`(string)`_.
func `'big`*(a: string): SomeType = discard
+
+##[
+
+Pandoc Markdown
+===============
+
+Now repeat all the auto links of above in Pandoc Markdown Syntax.
+
+Ref group [fn2] or specific function like [fn2()]
+or [fn2( int )] or [fn2(int,
+float)].
+
+Ref generics like this: [binarySearch] or [binarySearch(openArray[T], K,
+proc (T, K))] or [proc binarySearch(openArray[T], K, proc (T, K))] or
+in different style: [proc binarysearch(openarray[T], K, proc(T, K))].
+Can be combined with export symbols and type parameters:
+[binarysearch*[T, K](openArray[T], K, proc (T, K))].
+With spaces [binary search].
+
+Note that `proc` can be used in postfix form: [binarySearch proc].
+
+Ref. type like [G] and [type G] and [G[T]] and [type G*[T]].
+
+Group ref. with capital letters works: [fN11] or [fn11]
+
+Ref. [`[]`] is the same as [proc `[]`(G[T])] because there are no
+overloads. The full form: [proc `[]`*[T](x: G[T]): T]
+Ref. [`[]=`] aka [`[]=`(G[T], int, T)].
+Ref. [$] aka [proc $] or [proc `$`].
+Ref. [$(a: ref SomeType)].
+Ref. [foo_bar] aka [iterator foo_bar_].
+Ref. [fn[T; U,V: SomeFloat]()].
+Ref. ['big] or [func `'big`] or [`'big`(string)].
+
+Link name syntax
+----------------
+
+Pandoc Markdown has synax for changing text of links:
+Ref. [this proc][`[]`] or [another symbol][G[T]].
+
+Symbols documentation
+---------------------
+
+Let us repeat auto links from symbols section below:
+
+There is also variant [f(G[string])].
+See also [f(G[int])].
+
+]##
diff --git a/tests/stdlib/tdochelpers.nim b/tests/stdlib/tdochelpers.nim
index 8dcb158cac..0ad49427cd 100644
--- a/tests/stdlib/tdochelpers.nim
+++ b/tests/stdlib/tdochelpers.nim
@@ -10,74 +10,101 @@ discard """
import ../../lib/packages/docutils/[rstast, rst, dochelpers]
import unittest
-proc rstParseTest(text: string): PRstNode =
- proc testMsgHandler(filename: string, line, col: int, msgkind: MsgKind,
- arg: string) =
- doAssert msgkind == mwBrokenLink
+proc testMsgHandler(filename: string, line, col: int, msgkind: MsgKind,
+ arg: string) =
+ doAssert msgkind == mwBrokenLink
+
+proc fromRst(text: string): LangSymbol =
+ let r = rstParse(text, "-input-", LineRstInit, ColRstInit,
+ {roNimFile},
+ msgHandler=testMsgHandler)
+ assert r.node.kind == rnRstRef
+ result = toLangSymbol(r.node)
+
+proc fromMd(text: string): LangSymbol =
let r = rstParse(text, "-input-", LineRstInit, ColRstInit,
{roPreferMarkdown, roSupportMarkdown, roNimFile},
msgHandler=testMsgHandler)
- result = r.node
+ assert r.node.kind == rnPandocRef
+ assert r.node.len == 2
+ # this son is the target:
+ assert r.node.sons[1].kind == rnInner
+ result = toLangSymbol(r.node.sons[1])
suite "Integration with Nim":
test "simple symbol parsing (shortest form)":
- let input1 = "g_".rstParseTest
- check input1.toLangSymbol == LangSymbol(symKind: "", name: "g")
+ let expected = LangSymbol(symKind: "", name: "g")
+ check "g_".fromRst == expected
+ check "[g]".fromMd == expected
+ # test also alternative syntax variants of Pandoc Markdown:
+ check "[g][]".fromMd == expected
+ check "[this symbol][g]".fromMd == expected
test "simple symbol parsing (group of words)":
- let input1 = "`Y`_".rstParseTest
- check input1.toLangSymbol == LangSymbol(symKind: "", name: "Y")
+ #let input1 = "`Y`_".rstParseTest
+ let expected1 = LangSymbol(symKind: "", name: "Y")
+ check "`Y`_".fromRst == expected1
+ check "[Y]".fromMd == expected1
# this means not a statement 'type', it's a backticked identifier `type`:
- let input2 = "`type`_".rstParseTest
- check input2.toLangSymbol == LangSymbol(symKind: "", name: "type")
+ let expected2 = LangSymbol(symKind: "", name: "type")
+ check "`type`_".fromRst == expected2
+ check "[type]".fromMd == expected2
- let input3 = "`[]`_".rstParseTest
- check input3.toLangSymbol == LangSymbol(symKind: "", name: "[]")
+ let expected3 = LangSymbol(symKind: "", name: "[]")
+ check "`[]`_".fromRst == expected3
+ # Markdown syntax for this case is NOT [[]]
+ check "[`[]`]".fromMd == expected3
- let input4 = "`X Y Z`_".rstParseTest
- check input4.toLangSymbol == LangSymbol(symKind: "", name: "Xyz")
+ let expected4 = LangSymbol(symKind: "", name: "Xyz")
+ check "`X Y Z`_".fromRst == expected4
+ check "[X Y Z]".fromMd == expected4
test "simple proc parsing":
- let input1 = "proc f".rstParseTest
- check input1.toLangSymbol == LangSymbol(symKind: "proc", name: "f")
+ let expected = LangSymbol(symKind: "proc", name: "f")
+ check "`proc f`_".fromRst == expected
+ check "[proc f]".fromMd == expected
test "another backticked name":
- let input1 = """`template \`type\``_""".rstParseTest
- check input1.toLangSymbol == LangSymbol(symKind: "template", name: "type")
+ let expected = LangSymbol(symKind: "template", name: "type")
+ check """`template \`type\``_""".fromRst == expected
+ # no backslash in Markdown:
+ check """[template `type`]""".fromMd == expected
test "simple proc parsing with parameters":
- let input1 = "`proc f*()`_".rstParseTest
- let input2 = "`proc f()`_".rstParseTest
let expected = LangSymbol(symKind: "proc", name: "f",
parametersProvided: true)
- check input1.toLangSymbol == expected
- check input2.toLangSymbol == expected
+ check "`proc f*()`_".fromRst == expected
+ check "`proc f()`_".fromRst == expected
+ check "[proc f*()]".fromMd == expected
+ check "[proc f()]".fromMd == expected
test "symbol parsing with 1 parameter":
- let input = "`f(G[int])`_".rstParseTest
let expected = LangSymbol(symKind: "", name: "f",
parameters: @[("G[int]", "")],
parametersProvided: true)
- check input.toLangSymbol == expected
+ check "`f(G[int])`_".fromRst == expected
+ check "[f(G[int])]".fromMd == expected
test "more proc parsing":
- let input1 = "`proc f[T](x:G[T]):M[T]`_".rstParseTest
- let input2 = "`proc f[ T ] ( x: G [T] ): M[T]`_".rstParseTest
- let input3 = "`proc f*[T](x: G[T]): M[T]`_".rstParseTest
+ let input1 = "`proc f[T](x:G[T]):M[T]`_".fromRst
+ let input2 = "`proc f[ T ] ( x: G [T] ): M[T]`_".fromRst
+ let input3 = "`proc f*[T](x: G[T]): M[T]`_".fromRst
let expected = LangSymbol(symKind: "proc",
name: "f",
generics: "[T]",
parameters: @[("x", "G[T]")],
parametersProvided: true,
outType: "M[T]")
- check(input1.toLangSymbol == expected)
- check(input2.toLangSymbol == expected)
- check(input3.toLangSymbol == expected)
+ check(input1 == expected)
+ check(input2 == expected)
+ check(input3 == expected)
test "advanced proc parsing with Nim identifier normalization":
- let input = """`proc binarySearch*[T, K](a: openarray[T]; key: K;
- cmp: proc (x: T; y: K): int)`_""".rstParseTest
+ let inputRst = """`proc binarySearch*[T, K](a: openarray[T]; key: K;
+ cmp: proc (x: T; y: K): int)`_"""
+ let inputMd = """[proc binarySearch*[T, K](a: openarray[T]; key: K;
+ cmp: proc (x: T; y: K): int)]"""
let expected = LangSymbol(symKind: "proc",
name: "binarysearch",
generics: "[T,K]",
@@ -87,11 +114,12 @@ suite "Integration with Nim":
("cmp", "proc(x:T;y:K):int")],
parametersProvided: true,
outType: "")
- check(input.toLangSymbol == expected)
+ check(inputRst.fromRst == expected)
+ check(inputMd.fromMd == expected)
test "the same without proc":
let input = """`binarySearch*[T, K](a: openarray[T]; key: K;
- cmp: proc (x: T; y: K): int {.closure.})`_""".rstParseTest
+ cmp: proc (x: T; y: K): int {.closure.})`_"""
let expected = LangSymbol(symKind: "",
name: "binarysearch",
generics: "[T,K]",
@@ -101,27 +129,32 @@ suite "Integration with Nim":
("cmp", "proc(x:T;y:K):int")],
parametersProvided: true,
outType: "")
- check(input.toLangSymbol == expected)
+ check(input.fromRst == expected)
+ let inputMd = """[binarySearch*[T, K](a: openarray[T]; key: K;
+ cmp: proc (x: T; y: K): int {.closure.})]"""
+ check(inputMd.fromMd == expected)
test "operator $ with and without backticks":
- let input1 = """`func \`$\`*[T](a: \`open Array\`[T]): string`_""".
- rstParseTest
- let input2 = """`func $*[T](a: \`open Array\`[T]): string`_""".
- rstParseTest
+ let input1 = """`func \`$\`*[T](a: \`open Array\`[T]): string`_"""
+ let input1md = "[func `$`*[T](a: `open Array`[T]): string]"
+ let input2 = """`func $*[T](a: \`open Array\`[T]): string`_"""
+ let input2md = "[func $*[T](a: `open Array`[T]): string]"
let expected = LangSymbol(symKind: "func",
name: "$",
generics: "[T]",
parameters: @[("a", "openarray[T]")],
parametersProvided: true,
outType: "string")
- check(input1.toLangSymbol == expected)
- check(input2.toLangSymbol == expected)
+ check input1.fromRst == expected
+ check input2.fromRst == expected
+ check input1md.fromMd == expected
+ check input2md.fromMd == expected
test "operator [] with and without backticks":
- let input1 = """`func \`[]\`[T](a: \`open Array\`[T], idx: int): T`_""".
- rstParseTest
- let input2 = """`func [][T](a: \`open Array\`[T], idx: int): T`_""".
- rstParseTest
+ let input1 = """`func \`[]\`[T](a: \`open Array\`[T], idx: int): T`_"""
+ let input1md = "[func `[]`[T](a: `open Array`[T], idx: int): T]"
+ let input2 = """`func [][T](a: \`open Array\`[T], idx: int): T`_"""
+ let input2md = "[func [][T](a: `open Array`[T], idx: int): T]"
let expected = LangSymbol(symKind: "func",
name: "[]",
generics: "[T]",
@@ -129,21 +162,25 @@ suite "Integration with Nim":
("idx", "int")],
parametersProvided: true,
outType: "T")
- check(input1.toLangSymbol == expected)
- check(input2.toLangSymbol == expected)
+ check input1.fromRst == expected
+ check input2.fromRst == expected
+ check input1md.fromMd == expected
+ check input2md.fromMd == expected
test "postfix symbol specifier #1":
- let input = """`walkDir iterator`_""".
- rstParseTest
+ let input = "`walkDir iterator`_"
+ let inputMd = "[walkDir iterator]"
let expected = LangSymbol(symKind: "iterator",
name: "walkdir")
- check(input.toLangSymbol == expected)
+ check input.fromRst == expected
+ check inputMd.fromMd == expected
test "postfix symbol specifier #2":
- let input1 = """`\`[]\`[T](a: \`open Array\`[T], idx: int): T func`_""".
- rstParseTest
- let input2 = """`[][T](a: \`open Array\`[T], idx: int): T func`_""".
- rstParseTest
+ let input1 = """`\`[]\`[T](a: \`open Array\`[T], idx: int): T func`_"""
+ let input1md = "[`[]`[T](a: `open Array`[T], idx: int): T func]"
+ let input2 = """`[][T](a: \`open Array\`[T], idx: int): T func`_"""
+ # note again that ` is needed between 1st and second [
+ let input2md = "[`[]`[T](a: `open Array`[T], idx: int): T func]"
let expected = LangSymbol(symKind: "func",
name: "[]",
generics: "[T]",
@@ -151,11 +188,16 @@ suite "Integration with Nim":
("idx", "int")],
parametersProvided: true,
outType: "T")
- check(input1.toLangSymbol == expected)
- check(input2.toLangSymbol == expected)
+ check input1.fromRst == expected
+ check input2.fromRst == expected
+ check input1md.fromMd == expected
+ check input2md.fromMd == expected
test "type of type":
- check ("`CopyFlag enum`_".rstParseTest.toLangSymbol ==
- LangSymbol(symKind: "type",
- symTypeKind: "enum",
- name: "Copyflag"))
+ let inputRst = "`CopyFlag enum`_"
+ let inputMd = "[CopyFlag enum]"
+ let expected = LangSymbol(symKind: "type",
+ symTypeKind: "enum",
+ name: "Copyflag")
+ check inputRst.fromRst == expected
+ check inputMd.fromMd == expected
diff --git a/tests/stdlib/trst.nim b/tests/stdlib/trst.nim
index 32917d2575..0b6cbc071b 100644
--- a/tests/stdlib/trst.nim
+++ b/tests/stdlib/trst.nim
@@ -1173,7 +1173,7 @@ suite "Warnings":
lastParagraph
"""
var warnings = new seq[string]
- let output = input.toAst(warnings=warnings)
+ let output = input.toAst(rstOptions=preferRst, warnings=warnings)
check(warnings[] == @[
"input(3, 14) Warning: broken link 'citation-som'",
"input(5, 7) Warning: broken link 'a broken Link'",
@@ -1199,7 +1199,7 @@ suite "Warnings":
rnParagraph
rnLeaf 'here'
rnLeaf ' '
- rnRef
+ rnRstRef
rnLeaf 'brokenLink'
""")
removeFile("other.rst")
@@ -1558,7 +1558,7 @@ suite "RST inline markup":
test "no punctuation in the end of a standalone URI is allowed":
check(dedent"""
- [see (http://no.org)], end""".toAst ==
+ [see (http://no.org)], end""".toAst(rstOptions = preferRst) ==
dedent"""
rnInner
rnLeaf '['
@@ -1606,6 +1606,19 @@ suite "RST inline markup":
rnLeaf 'end'
""")
+ test "Markdown-style link can be split to a few lines":
+ check(dedent"""
+ is [term-rewriting
+ macros](manual.html#term-rewriting-macros)""".toAst ==
+ dedent"""
+ rnInner
+ rnLeaf 'is'
+ rnLeaf ' '
+ rnHyperlink
+ rnLeaf 'term-rewriting macros'
+ rnLeaf 'manual.html#term-rewriting-macros'
+ """)
+
test "URL with balanced parentheses (Markdown rule)":
# 2 balanced parens, 1 unbalanced:
check(dedent"""
diff --git a/tests/stdlib/trstgen.nim b/tests/stdlib/trstgen.nim
index 8e05f80b70..6edacfc248 100644
--- a/tests/stdlib/trstgen.nim
+++ b/tests/stdlib/trstgen.nim
@@ -983,7 +983,7 @@ Test1
Ref. [#note]_
"""
- let output1 = input1.toHtml
+ let output1 = input1.toHtml(preferRst)
doAssert output1.count(">[1]") == 1
doAssert output1.count(">[2]") == 2
doAssert "href=\"#footnote-note\"" in output1
@@ -1001,7 +1001,7 @@ Test1
Not references[#note]_[1 #]_ [wrong citation]_ and [not&allowed]_.
"""
- let output2 = input2.toHtml
+ let output2 = input2.toHtml(preferRst)
doAssert output2 == "Not references[#note]_[1 #]_ [wrong citation]_ and [not&allowed]_."
# check that auto-symbol footnotes work:
@@ -1017,7 +1017,7 @@ Test1
And [*]_.
"""
- let output3 = input3.toHtml
+ let output3 = input3.toHtml(preferRst)
# both references and footnotes. Footnotes have link to themselves.
doAssert output3.count("href=\"#footnotesym-1\">[*]") == 2
doAssert output3.count("href=\"#footnotesym-2\">[**]") == 2
@@ -1047,7 +1047,7 @@ Test1
Ref. [#note]_ and [#]_ and [#]_.
"""
- let output4 = input4.toHtml
+ let output4 = input4.toHtml(preferRst)
doAssert ">[-1]" notin output1
let order = @[
"footnote-3", "[3]", "Manual1.",
@@ -1072,7 +1072,7 @@ Test1
Ref. [#note]_
"""
var error5 = new string
- let output5 = input5.toHtml(error=error5)
+ let output5 = input5.toHtml(preferRst, error=error5)
check(error5[] == "input(1, 1) Error: mismatch in number of footnotes " &
"and their refs: 1 (lines 2) != 0 (lines ) for auto-numbered " &
"footnotes")
@@ -1086,7 +1086,7 @@ Test1
Ref. [*]_
"""
var error6 = new string
- let output6 = input6.toHtml(error=error6)
+ let output6 = input6.toHtml(preferRst, error=error6)
check(error6[] == "input(1, 1) Error: mismatch in number of footnotes " &
"and their refs: 1 (lines 3) != 2 (lines 2, 6) for auto-symbol " &
"footnotes")
@@ -1096,7 +1096,7 @@ Test1
Ref. [some:citation-2020]_.
"""
- let output7 = input7.toHtml
+ let output7 = input7.toHtml(preferRst)
doAssert output7.count("href=\"#citation-somecoloncitationminus2020\"") == 2
doAssert output7.count("[Some:CITATION-2020]") == 1
doAssert output7.count("[some:citation-2020]") == 1
@@ -1109,7 +1109,7 @@ Test1
Ref. [som]_.
"""
var warnings8 = new seq[string]
- let output8 = input8.toHtml(warnings=warnings8)
+ let output8 = input8.toHtml(preferRst, warnings=warnings8)
check(warnings8[] == @["input(3, 7) Warning: broken link 'citation-som'"])
# check that footnote group does not break parsing of other directives:
@@ -1145,7 +1145,7 @@ Test1
.. [Third] Citation.
"""
- let output10 = input10.toHtml
+ let output10 = input10.toHtml(preferRst)
doAssert output10.count("" &
"