-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve Markdown code blocks & start moving docs to Markdown style #19954
Conversation
- 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 nim-lang/RFCs#355 - better error messages - (other) fix a bug that admonitions cannot be used in sandbox mode; fix annoying warning on line 2711
|
Ping @Araq |
Fyi even heavy refactorings like "reimplemented the markdown parser and it's not based anymore on the RST parser" will be accepted. RST is dead, Markdown has won. |
Also, if you tell me your personal information via e-mail I'll send you a signed copy of "Mastering Nim" as a reward for your outstanding work on Nim's doc gen. |
Thanks for your hard work on this PR! Hint: mm: orc; threads: on; opt: speed; options: -d:release |
…im-lang#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 nim-lang/RFCs#355 - better error messages - (other) fix a bug that admonitions cannot be used in sandbox mode; fix annoying warning on line 2711
…im-lang#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 nim-lang/RFCs#355 - better error messages - (other) fix a bug that admonitions cannot be used in sandbox mode; fix annoying warning on line 2711
add additional parameters parsing (other implementations will just ignore them). E.g. if in RST we have
:test:
:then in Markdown that will be:
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 interprets it as quoted block, for Markdown it's just normal paragraphs. Fixes bug 23 of RST minor bugs #17340.
fix indentation inside Markdown code blocks — additional indentation is preserved there — bug 22 of RST minor bugs #17340
add separate
md2html
andmd2tex
commands. This is to separate Markdown behavior in cases when it diverges w.r.t. RST significantly — most conspicuously like in the case of additional indentation above, and also currently the contradicting inline rule of Markdown is also turned on only inmd2html
andmd2tex
. 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 Markdownand RST features enabled. In this PR
*.nim
files can be processed only in Markdown mode, whilemd2html
is for*.md
files andrst2html
for*.rst
files.rename
*.rst
files to.*md
as our current default behavior isalready 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
allow more than 3 back-ticks open/close blocks (tildes ~ are still not allowed to avoid conflict with RST adornment headings) see also universal inline code block syntax for nim doc+rst RFCs#355
better error messages
(other) fix a bug that admonitions cannot be used in sandbox mode; fix annoying warning on line 2711
Current rendering of
.md
files in Github is far from being optimal, see e.g. Manual: https://github.com/a-mr/Nim/blob/markdown-better-code-blocks/doc/manual.md, which is partially because we use~~~
asheading adornments
but they are interpreted as code blocks in Markdown.