jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Markdown indented code blocks (#20473)

Browse source 
* Implement Markdown indented code blocks

Additional indentation of 4 spaces makes a block an "indented code block"
(monospaced text without syntax highlighting).
Also `::` RST syntax for code blocks is disabled.

So instead of
```rst
see::

  Some code
```

the code block should be written as
```markdown
see:

    Some code
```

* Migrate RST literal blocks :: to Markdown's ones
This commit is contained in:
Andrey Makarov 2022-10-05 21:03:10 +03:00 • committed by GitHub
commit 6505bd347d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
33 changed files with 697 additions and 603 deletions
Download patch file Download diff file Expand all files Collapse all files

171
doc/docgen.md
View file

@ -64,10 +64,11 @@ Example:
age: int
```
Outputs::
Person* = object
name: string
age: int
Outputs:
Person* = object
name: string
age: int
This type contains a description of a person
@ -133,10 +134,11 @@ The `doc`:option: command:
nim doc docgen_sample.nim
```
Partial Output::
...
proc helloWorld(times: int) {.raises: [], tags: [].}
...
Partial Output:
...
proc helloWorld(times: int) {.raises: [], tags: [].}
...
The full output can be seen here: [docgen_sample.html](docgen_sample.html).
It runs after semantic checking and includes pragmas attached implicitly by the
@ -179,22 +181,23 @@ The `jsondoc`:option: command:
nim jsondoc docgen_sample.nim
```
Output::
{
"orig": "docgen_sample.nim",
"nimble": "",
"moduleDescription": "This module is a sample",
"entries": [
{
"name": "helloWorld",
"type": "skProc",
"line": 5,
"col": 0,
"description": "Takes an integer and outputs as many "hello world!"s",
"code": "proc helloWorld(times: int) {.raises: [], tags: [].}"
}
]
}
Output:
{
"orig": "docgen_sample.nim",
"nimble": "",
"moduleDescription": "This module is a sample",
"entries": [
{
"name": "helloWorld",
"type": "skProc",
"line": 5,
"col": 0,
"description": "Takes an integer and outputs as many "hello world!"s",
"code": "proc helloWorld(times: int) {.raises: [], tags: [].}"
}
]
}
Similarly to the old `doc`:option: command, the old `jsondoc`:option: command has been
renamed to `jsondoc0`:option:.
@ -205,18 +208,19 @@ The `jsondoc0`:option: command:
nim jsondoc0 docgen_sample.nim
```
Output::
[
{
"comment": "This module is a sample."
},
{
"name": "helloWorld",
"type": "skProc",
"description": "Takes an integer and outputs as many "hello world!"s",
"code": "proc helloWorld*(times: int)"
}
]
Output:
[
{
"comment": "This module is a sample."
},
{
"name": "helloWorld",
"type": "skProc",
"description": "Takes an integer and outputs as many "hello world!"s",
"code": "proc helloWorld*(times: int)"
}
]
Note that the `jsondoc`:option: command outputs its JSON without pretty-printing it,
while `jsondoc0`:option: outputs pretty-printed JSON.
@ -247,10 +251,13 @@ If you have a constant:
then it should be referenced in one of the 2 forms:
A. non-qualified (no symbol kind specification)::
pi_
B. qualified (with symbol kind specification)::
`const pi`_
A. non-qualified (no symbol kind specification):
pi_
B. qualified (with symbol kind specification):
`const pi`_
For routine kinds there are more options. Consider this definition:
@ -262,52 +269,52 @@ Generally following syntax is allowed for referencing `foo`:
* short (without parameters):
A. non-qualified::
A. non-qualified:
foo_
foo_
B. qualified::
B. qualified:
`proc foo`_
`proc foo`_
* longer variants (with parameters):
A. non-qualified:
1) specifying parameters names::
1) specifying parameters names:
`foo(a, b)`_
`foo(a, b)`_
2) specifying parameters types::
2) specifying parameters types:
`foo(int, float)`_
`foo(int, float)`_
3) specifying both names and types::
3) specifying both names and types:
`foo(a: int, b: float)`_
`foo(a: int, b: float)`_
4) output parameter can also be specified if you wish::
4) output parameter can also be specified if you wish:
`foo(a: int, b: float): string`_
`foo(a: int, b: float): string`_
B. qualified: all 4 options above are valid.
Particularly you can use the full format::
Particularly you can use the full format:
`proc foo(a: int, b: float): string`_
`proc foo(a: int, b: float): string`_
.. Tip:: Avoid cluttering your text with extraneous information by using
one of shorter forms::
one of shorter forms:
binarySearch_
`binarySearch(a, key, cmp)`_
binarySearch_
`binarySearch(a, key, cmp)`_
Brevity is better for reading! If you use a short form and have an
ambiguity problem (see below) then just add some additional info.
Symbol kind like `proc` can also be specified in the postfix form::
Symbol kind like `proc` can also be specified in the postfix form:
`foo proc`_
`walkDir(d: string) iterator`_
`foo proc`_
`walkDir(d: string) iterator`_
.. Warning:: An ambiguity in resolving documentation links may arise because of:
@ -320,9 +327,9 @@ Symbol kind like `proc` can also be specified in the postfix form::
`proc` and `template`. In this case they are split between their
corresponding sections in output file. Qualified references are
useful in this case -- just disambiguate by referring to these
sections explicitly::
sections explicitly:
See `foo proc`_ and `foo template`_.
See `foo proc`_ and `foo template`_.
* because in Nim `proc` and `iterator` belong to different namespaces,
so there can be a collision even if parameters are the same.
@ -334,9 +341,9 @@ Symbol kind like `proc` can also be specified in the postfix form::
(while procs have higher priority than other Nim symbol kinds).
Generic parameters can also be used. All in all, this long form will be
recognized fine::
recognized fine:
`proc binarySearch*[T; K](a: openArray[T], key: K, cmp: proc(T, K)): int`_
`proc binarySearch*[T; K](a: openArray[T], key: K, cmp: proc(T, K)): int`_
**Limitations**:
@ -351,16 +358,16 @@ recognized fine::
```
you cannot use names underlined by `~~` so it must be referenced with
``cmp: proc(T, K)``. Hence these forms are valid::
``cmp: proc(T, K)``. Hence these forms are valid:
`binarySearch(a: openArray[T], key: K, cmp: proc(T, K))`_
`binarySearch(openArray[T], K, proc(T, K))`_
`binarySearch(a, key, cmp)`_
`binarySearch(a: openArray[T], key: K, cmp: proc(T, K))`_
`binarySearch(openArray[T], K, proc(T, K))`_
`binarySearch(a, key, cmp)`_
2. Default values in routine parameters are not recognized, one needs to
specify the type and/or name instead. E.g. for referencing `proc f(x = 7)`
use one of the mentioned forms::
use one of the mentioned forms:
`f(int)`_ or `f(x)`_ or `f(x: int)`_.
`f(int)`_ or `f(x)`_ or `f(x: int)`_.
3. Generic parameters must be given the same way as in the
definition of referenced symbol.
@ -376,27 +383,27 @@ recognized fine::
func `[]`*[T](x: openArray[T]): T
```
A short form works without additional backticks::
A short form works without additional backticks:
`$`_
`[]`_
`$`_
`[]`_
However for fully-qualified reference copy-pasting backticks (`) into other
backticks will not work in our RST parser (because we use Markdown-like
inline markup rules). You need either to delete backticks or keep
them and escape with backslash \\::
them and escape with backslash \\:
no backticks: `func $`_
escaped: `func \`$\``_
no backticks: `func [][T](x: openArray[T]): T`_
escaped: `func \`[]\`[T](x: openArray[T]): T`_
no backticks: `func $`_
escaped: `func \`$\``_
no backticks: `func [][T](x: openArray[T]): T`_
escaped: `func \`[]\`[T](x: openArray[T]): T`_
.. Note:: Types that defined as `enum`, or `object`, or `tuple` can also be
referenced with those names directly (instead of `type`)::
referenced with those names directly (instead of `type`):
type CopyFlag = enum
...
## Ref. `CopyFlag enum`_
type CopyFlag = enum
...
## Ref. `CopyFlag enum`_
Related Options
===============