mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-06-06 03:44:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
Andrey Makarov
2022-07-15 20:27:54 +03:00
committed by GitHub
parent f35c9cf73d
commit 417b90a7e5
47 changed files with 341 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
tests/stdlib/thighlite.nim
View File

@@ -12,6 +12,12 @@ block: # Nim tokenizing
@[("\"\"\"ok1\\nok2\\nok3\"\"\"", gtLongStringLit)
])
test "whitespace at beginning of line is preserved":
check(" discard 1".tokenize(langNim) ==
@[(" ", gtWhitespace), ("discard", gtKeyword), (" ", gtWhitespace),
("1", gtDecNumber)
])
block: # Cmd (shell) tokenizing
test "cmd with dollar and output":
check(

117
tests/stdlib/trst.nim
View File

@@ -24,8 +24,11 @@ import unittest, strutils
import std/private/miscdollars
import os
const preferMarkdown = {roPreferMarkdown, roSupportMarkdown, roNimFile, roSandboxDisabled}
const preferRst = {roSupportMarkdown, roNimFile, roSandboxDisabled}
proc toAst(input: string,
rstOptions: RstParseOptions = {roPreferMarkdown, roSupportMarkdown, roNimFile, roSandboxDisabled},
rstOptions: RstParseOptions = preferMarkdown,
error: ref string = nil,
warnings: ref seq[string] = nil): string =
## If `error` is nil then no errors should be generated.
@@ -451,7 +454,7 @@ suite "RST parsing":
> - y
>
> Paragraph.
""".toAst == dedent"""
""".toAst(rstOptions = preferRst) == dedent"""
rnMarkdownBlockQuote
rnMarkdownBlockQuoteItem quotationDepth=1
rnInner
@@ -468,6 +471,93 @@ suite "RST parsing":
rnLeaf '.'
""")
test "Markdown code blocks with more > 3 backticks":
check(dedent"""
````
let a = 1
```
````""".toAst ==
dedent"""
rnCodeBlock
[nil]
[nil]
rnLiteralBlock
rnLeaf '
let a = 1
```'
""")
test "Markdown code blocks with Nim-specific arguments":
check(dedent"""
```nim number-lines=1 test
let a = 1
```""".toAst ==
dedent"""
rnCodeBlock
rnDirArg
rnLeaf 'nim'
rnFieldList
rnField
rnFieldName
rnLeaf 'number-lines'
rnFieldBody
rnLeaf '1'
rnField
rnFieldName
rnLeaf 'test'
rnFieldBody
rnLiteralBlock
rnLeaf '
let a = 1'
""")
check(dedent"""
```nim test = "nim c $1" number-lines = 1
let a = 1
```""".toAst ==
dedent"""
rnCodeBlock
rnDirArg
rnLeaf 'nim'
rnFieldList
rnField
rnFieldName
rnLeaf 'test'
rnFieldBody
rnLeaf '"nim c $1"'
rnField
rnFieldName
rnLeaf 'number-lines'
rnFieldBody
rnLeaf '1'
rnLiteralBlock
rnLeaf '
let a = 1'
""")
test "additional indentation < 4 spaces is handled fine":
check(dedent"""
Indentation
```nim
let a = 1
```""".toAst ==
dedent"""
rnInner
rnParagraph
rnLeaf 'Indentation'
rnParagraph
rnCodeBlock
rnDirArg
rnLeaf 'nim'
[nil]
rnLiteralBlock
rnLeaf '
let a = 1'
""")
# | |
# | \ indentation of exactly two spaces before 'let a = 1'
test "option list has priority over definition list":
check(dedent"""
--defusages
@@ -562,7 +652,7 @@ suite "RST parsing":
notAcomment1
notAcomment2
someParagraph""".toAst ==
someParagraph""".toAst(rstOptions = preferRst) ==
dedent"""
rnInner
rnBlockQuote
@@ -574,6 +664,25 @@ suite "RST parsing":
rnLeaf 'someParagraph'
""")
test "check that additional line right after .. ends comment (Markdown mode)":
# in Markdown small indentation does not matter so this should
# just be split to 2 paragraphs.
check(dedent"""
..
notAcomment1
notAcomment2
someParagraph""".toAst ==
dedent"""
rnInner
rnInner
rnLeaf 'notAcomment1'
rnLeaf ' '
rnLeaf 'notAcomment2'
rnParagraph
rnLeaf 'someParagraph'
""")
test "but blank lines after 2nd non-empty line don't end the comment":
check(dedent"""
..
@@ -592,7 +701,7 @@ suite "RST parsing":
..
someBlockQuote""".toAst ==
someBlockQuote""".toAst(rstOptions = preferRst) ==
dedent"""
rnInner
rnAdmonition adType=note

16
tests/stdlib/trstgen.nim
View File

@@ -9,8 +9,13 @@ import ../../lib/packages/docutils/rst
import unittest, strutils, strtabs
import std/private/miscdollars
const
NoSandboxOpts = {roPreferMarkdown, roSupportMarkdown, roNimFile, roSandboxDisabled}
preferMarkdown = {roPreferMarkdown, roSupportMarkdown, roNimFile}
preferRst = {roSupportMarkdown, roNimFile}
proc toHtml(input: string,
rstOptions: RstParseOptions = {roPreferMarkdown, roSupportMarkdown, roNimFile},
rstOptions: RstParseOptions = preferMarkdown,
error: ref string = nil,
warnings: ref seq[string] = nil): string =
## If `error` is nil then no errors should be generated.
@@ -47,9 +52,6 @@ proc optionListLabel(opt: string): string =
opt &
"</span></tt></div>"
const
NoSandboxOpts = {roPreferMarkdown, roSupportMarkdown, roNimFile, roSandboxDisabled}
suite "YAML syntax highlighting":
test "Basics":
@@ -1180,7 +1182,7 @@ Test1
"input(8, 4) Warning: language 'anotherLang' not supported"
])
check(output == "<pre class = \"listing\">anything</pre>" &
"<p><pre class = \"listing\">\nsomeCode\n</pre> </p>")
"<p><pre class = \"listing\">\nsomeCode</pre> </p>")
test "RST admonitions":
# check that all admonitions are implemented
@@ -1321,7 +1323,7 @@ Test1
That was a transition.
"""
let output1 = input1.toHtml(
NoSandboxOpts
preferRst
)
doAssert "<p id=\"target000\"" in output1
doAssert "<ul id=\"target001\"" in output1
@@ -1543,7 +1545,7 @@ Test1
"""<td>text</td></tr>""" & "\n</tbody></table>")
test "Field list: body after newline":
let output = dedent """
let output = dedent"""
:field:
text1""".toHtml
check "<table class=\"docinfo\"" in output