Skip to content

Commit ae3dd75

Browse files
a-mra-mr
authored
Extract markdown/rst doc into separate file (#20404)
* Extract Markdown & Rst doc into separate file This documentation should be extracted into separate file as it's user's documentation, which can be used as a separate utility for compiling `.md/.rst` files. * Restructure: move markup info into markdown_rst.md +Markdown link migration
1 parent 2afce84 commit ae3dd75

File tree

3 files changed

+271
-247
lines changed

3 files changed

+271
-247
lines changed

‎doc/docgen.md‎

Lines changed: 5 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,6 @@ from input ``.nim`` files and projects, as well as HTML and LaTeX from input RST
2020
dependencies (`import`), any top-level documentation comments (`##`), and
2121
exported symbols (`*`), including procedures, types, and variables.
2222

23-
=================== ====================== ============ ==============
24-
command runs on... input format output format
25-
=================== ====================== ============ ==============
26-
`nim doc`:cmd: documentation comments ``.nim`` ``.html`` HTML
27-
`nim doc2tex`:cmd: ″ ″ ``.tex`` LaTeX
28-
`nim jsondoc`:cmd: ″ ″ ``.json`` JSON
29-
`nim rst2html`:cmd: standalone rst files ``.rst`` ``.html`` HTML
30-
`nim rst2tex`:cmd: ″ ″ ``.tex`` LaTeX
31-
=================== ====================== ============ ==============
32-
3323
Quick start
3424
-----------
3525

@@ -490,18 +480,8 @@ highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also
490480
supports highlighting of a few other languages supported by the
491481
[packages/docutils/highlite module](highlite.html).
492482

493-
Usage:
494-
495-
```cmd
496-
nim rst2html docgen.rst
497-
```
498-
499-
Output::
500-
You're reading it!
501-
502-
The `rst2tex`:option: command is invoked identically to `rst2html`:option:,
503-
but outputs a ``.tex`` file instead of ``.html``.
504-
483+
See [Markdown and RST markup languages](markdown_rst.html) for
484+
usage of those commands.
505485

506486
HTML anchor generation
507487
======================
@@ -628,10 +608,9 @@ Additional resources
628608

629609
* [Nim Compiler User Guide](nimc.html#compiler-usage-commandminusline-switches)
630610

631-
* Documentation for [rst module](rst.html) -- Nim RST/Markdown parser.
632-
633-
* [RST Quick Reference](
634-
http://docutils.sourceforge.net/docs/user/rst/quickref.html)
611+
* already mentioned documentation for
612+
[Markdown and RST markup languages](markdown_rst.html), which also
613+
contains the list of implemented features of these markup languages.
635614

636615
The output for HTML and LaTeX comes from the ``config/nimdoc.cfg`` and
637616
``config/nimdoc.tex.cfg`` configuration files. You can add and modify these

‎doc/markdown_rst.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
==========================================
2+
Nim-flavored Markdown and reStructuredText
3+
==========================================
4+
5+
:Author: Andrey Makarov
6+
:Version: |nimversion|
7+
8+
.. default-role:: code
9+
.. include:: rstcommon.rst
10+
.. contents::
11+
12+
Both `Markdown`:idx: (md) and `reStructuredText`:idx: (RST) are markup
13+
languages whose goal is to typeset texts with complex structure,
14+
formatting and references using simple plaintext representation.
15+
16+
Command line usage
17+
==================
18+
19+
Usage (to convert Markdown into HTML):
20+
21+
```cmd
22+
nim md2html markdown_rst.md
23+
```
24+
25+
Output::
26+
You're reading it!
27+
28+
The `md2tex`:option: command is invoked identically to `md2html`:option:,
29+
but outputs a ``.tex`` file instead of ``.html``.
30+
31+
These tools embedded into Nim compiler; the compiler can output
32+
the result to HTML \[#html] or Latex \[#latex].
33+
34+
\[#html] commands `nim doc`:cmd: for ``*.nim`` files and
35+
`nim rst2html`:cmd: for ``*.rst`` files
36+
37+
\[#latex] commands `nim doc2tex`:cmd: for ``*.nim`` and
38+
`nim rst2tex`:cmd: for ``*.rst``.
39+
40+
Full list of supported commands:
41+
42+
=================== ====================== ============ ==============
43+
command runs on... input format output format
44+
=================== ====================== ============ ==============
45+
`nim md2html`:cmd: standalone md files ``.md`` ``.html`` HTML
46+
`nim md2tex`:cmd: same same ``.tex`` LaTeX
47+
`nim rst2html`:cmd: standalone rst files ``.rst`` ``.html`` HTML
48+
`nim rst2tex`:cmd: same same ``.tex`` LaTeX
49+
`nim doc`:cmd: documentation comments ``.nim`` ``.html`` HTML
50+
`nim doc2tex`:cmd: same same ``.tex`` LaTeX
51+
`nim jsondoc`:cmd: same same ``.json`` JSON
52+
=================== ====================== ============ ==============
53+
54+
55+
Basic markup
56+
============
57+
58+
If you are new to Markdown/RST please consider reading the following:
59+
60+
1) [Markdown Basic Syntax]
61+
2) a long specification of Markdown: [CommonMark Spec]
62+
3) a short [quick introduction] to RST
63+
4) an [RST reference]: a comprehensive cheatsheet for RST
64+
5) a more formal 50-page [RST specification].
65+
66+
Features
67+
--------
68+
69+
A large subset is implemented with some [limitations] and
70+
[additional Nim-specific features].
71+
72+
Supported standard RST features:
73+
74+
* body elements
75+
+ sections
76+
+ transitions
77+
+ paragraphs
78+
+ bullet lists using \+, \*, \-
79+
+ enumerated lists using arabic numerals or alphabet
80+
characters: 1. ... 2. ... *or* a. ... b. ... *or* A. ... B. ...
81+
+ footnotes (including manually numbered, auto-numbered, auto-numbered
82+
with label, and auto-symbol footnotes) and citations
83+
+ definition lists
84+
+ field lists
85+
+ option lists
86+
+ indented literal blocks
87+
+ quoted literal blocks
88+
+ line blocks
89+
+ simple tables
90+
+ directives (see official documentation in [RST directives list]):
91+
- ``image``, ``figure`` for including images and videos
92+
- ``code``
93+
- ``contents`` (table of contents), ``container``, ``raw``
94+
- ``include``
95+
- admonitions: "attention", "caution", "danger", "error", "hint",
96+
"important", "note", "tip", "warning", "admonition"
97+
- substitution definitions: `replace` and `image`
98+
+ comments
99+
* inline markup
100+
+ *emphasis*, **strong emphasis**,
101+
``inline literals``, hyperlink references (including embedded URI),
102+
substitution references, standalone hyperlinks,
103+
internal links (inline and outline)
104+
+ \`interpreted text\` with roles ``:literal:``, ``:strong:``,
105+
``emphasis``, ``:sub:``/``:subscript:``, ``:sup:``/``:superscript:``
106+
(see [RST roles list] for description).
107+
+ inline internal targets
108+
109+
Additional Nim-specific features
110+
--------------------------------
111+
112+
* directives: ``code-block`` \[cmp:Sphinx], ``title``,
113+
``index`` \[cmp:Sphinx]
114+
* predefined roles
115+
- ``:nim:`` (default), ``:c:`` (C programming language),
116+
``:python:``, ``:yaml:``, ``:java:``, ``:cpp:`` (C++), ``:csharp`` (C#).
117+
That is every language that [highlite](highlite.html) supports.
118+
They turn on appropriate syntax highlighting in inline code.
119+
120+
.. Note:: default role for Nim files is ``:nim:``,
121+
for ``*.rst`` it's currently ``:literal:``.
122+
123+
- generic command line highlighting roles:
124+
- ``:cmd:`` for commands and common shells syntax
125+
- ``:console:`` the same for interactive sessions
126+
(commands should be prepended by ``$``)
127+
- ``:program:`` for executable names \[cmp:Sphinx]
128+
(one can just use ``:cmd:`` on single word)
129+
- ``:option:`` for command line options \[cmp:Sphinx]
130+
- ``:tok:``, a role for highlighting of programming language tokens
131+
* ***triple emphasis*** (bold and italic) using \*\*\*
132+
* ``:idx:`` role for \`interpreted text\` to include the link to this
133+
text into an index (example: [Nim index]).
134+
* double slash `//` in option lists serves as a prefix for any option that
135+
starts from a word (without any leading symbols like `-`, `--`, `/`)::
136+
137+
//compile compile the project
138+
//doc generate documentation
139+
140+
Here the dummy `//` will disappear, while options `compile`:option:
141+
and `doc`:option: will be left in the final document.
142+
143+
\[cmp:Sphinx] similar but different from the directives of
144+
Python [Sphinx directives] and [Sphinx roles] extensions
145+
146+
Extra features
147+
--------------
148+
149+
Optional additional features, by default turned on:
150+
151+
* emoji / smiley symbols
152+
* Markdown tables
153+
* Markdown code blocks. For them the same additional arguments as for RST
154+
code blocks can be provided (e.g. `test` or `number-lines`) but with
155+
a one-line syntax like this::
156+
157+
```nim test number-lines=10
158+
echo "ok"
159+
```
160+
* Markdown links
161+
* Markdown headlines
162+
* Markdown block quotes
163+
* using ``1`` as auto-enumerator in enumerated lists like RST ``#``
164+
(auto-enumerator ``1`` can not be used with ``#`` in the same list)
165+
166+
.. Note:: By default Nim has ``roSupportMarkdown`` and
167+
``roSupportRawDirective`` turned **on**.
168+
169+
.. warning:: Using Nim-specific features can cause other RST implementations
170+
to fail on your document.
171+
172+
Idiosyncrasies
173+
--------------
174+
175+
Currently we do **not** aim at 100% Markdown or RST compatibility in inline
176+
markup recognition rules because that would provide very little user value.
177+
This parser has 2 modes for inline markup:
178+
179+
1) Markdown-like mode which is enabled by `roPreferMarkdown` option
180+
(turned **on** by default).
181+
182+
.. Note:: RST features like directives are still turned **on**
183+
184+
2) Compatibility mode which is RST rules.
185+
186+
.. Note:: in both modes the parser interpretes text between single
187+
backticks (code) identically:
188+
backslash does not escape; the only exception: ``\`` folowed by `
189+
does escape so that we can always input a single backtick ` in
190+
inline code. However that makes impossible to input code with
191+
``\`` at the end in *single* backticks, one must use *double*
192+
backticks::
193+
194+
`\` -- WRONG
195+
``\`` -- GOOD
196+
So single backticks can always be input: `\`` will turn to ` code
197+
198+
.. Attention::
199+
We don't support some obviously poor design choices of Markdown (or RST).
200+
201+
- no support for the rule of 2 spaces causing a line break in Markdown
202+
(use RST "line blocks" syntax for making line breaks)
203+
204+
- interpretation of Markdown block quotes is also slightly different,
205+
e.g. case
206+
207+
::
208+
209+
>>> foo
210+
> bar
211+
>>baz
212+
213+
is a single 3rd-level quote `foo bar baz` in original Markdown, while
214+
in Nim we naturally see it as 3rd-level quote `foo` + 1st level `bar` +
215+
2nd level `baz`:
216+
217+
>>> foo
218+
> bar
219+
>>baz
220+
221+
Limitations
222+
-----------
223+
224+
* no Unicode support in character width calculations
225+
* body elements
226+
- no roman numerals in enumerated lists
227+
- no doctest blocks
228+
- no grid tables
229+
- some directives are missing (check official [RST directives list]):
230+
``parsed-literal``, ``sidebar``, ``topic``, ``math``, ``rubric``,
231+
``epigraph``, ``highlights``, ``pull-quote``, ``compound``,
232+
``table``, ``csv-table``, ``list-table``, ``section-numbering``,
233+
``header``, ``footer``, ``meta``, ``class``
234+
- no ``role`` directives and no custom interpreted text roles
235+
- some standard roles are not supported (check [RST roles list])
236+
- no generic admonition support
237+
* inline markup
238+
- no simple-inline-markup
239+
- no embedded aliases
240+
241+
Additional resources
242+
--------------------
243+
244+
* See [Nim DocGen Tools Guide](docgen.html) for the details about
245+
`nim doc`:cmd: command and idiosyncrasies of documentation markup in
246+
``.nim`` files and Nim programming language projects.
247+
* See also documentation for [rst module](rst.html) -- Nim RST/Markdown parser.
248+
249+
.. _Markdown Basic Syntax: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
250+
.. _CommonMark Spec: https://spec.commonmark.org/0.30
251+
.. _quick introduction: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
252+
.. _RST reference: https://docutils.sourceforge.io/docs/user/rst/quickref.html
253+
.. _RST specification: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
254+
.. _RST directives list: https://docutils.sourceforge.io/docs/ref/rst/directives.html
255+
.. _RST roles list: https://docutils.sourceforge.io/docs/ref/rst/roles.html
256+
.. _Nim index: https://nim-lang.org/docs/theindex.html
257+
.. _Sphinx directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
258+
.. _Sphinx roles: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html

0 commit comments

Comments
 (0)