diff options
Diffstat (limited to 'doc/docgen.md')
| -rw-r--r-- | doc/docgen.md | 34 |
1 files changed, 28 insertions, 6 deletions
diff --git a/doc/docgen.md b/doc/docgen.md index 9e0a83bab..a05da8198 100644 --- a/doc/docgen.md +++ b/doc/docgen.md @@ -16,11 +16,26 @@ Introduction This document describes the `documentation generation tools`:idx: built into the [Nim compiler](nimc.html), which can generate HTML, Latex and JSON output -from input ``.nim`` files and projects, as well as HTML and LaTeX from input RST -(reStructuredText) files. The output documentation will include the module +from input ``.nim`` files and projects. +The output documentation will include the module dependencies (`import`), any top-level documentation comments (`##`), and exported symbols (`*`), including procedures, types, and variables. +=================== ============== +command output format +=================== ============== +`nim doc`:cmd: ``.html`` HTML +`nim doc2tex`:cmd: ``.tex`` LaTeX +`nim jsondoc`:cmd: ``.json`` JSON +=================== ============== + +Nim can generate HTML and LaTeX from input Markdown and +RST (reStructuredText) files as well, which is intended for writing +standalone documents like user's guides and technical specifications. +See [Nim-flavored Markdown and reStructuredText] document for the description +of this feature and particularly section [Command line usage] for the full +list of supported commands. + Quick start ----------- @@ -319,6 +334,15 @@ external referencing requires to use ``.. importdoc:: <file>`` directive to import `file` and to ensure that the corresponding ``.idx`` file was generated. +Syntax for referencing is basically the same as for normal markup. +Recall from [Referencing] that our parser supports two equivalent syntaxes +for referencing, Markdown and RST one. +So to reference ``proc f`` one should use something like that, +depending on markup type: + + Markdown RST + + Ref. [proc f] or [f] Ref. `proc f`_ or just f_ for a one-word case Nim local referencing --------------------- @@ -327,10 +351,8 @@ You can reference Nim identifiers from Nim documentation comments inside their ``.nim`` file (or inside a ``.rst`` file included from a ``.nim``). This pertains to any exported symbol like `proc`, `const`, `iterator`, etc. -Syntax for referencing is basically a normal RST one: addition of -underscore `_` to a *link text*. -Link text is either one word or a group of words enclosed by backticks `\`` -(for a one word case backticks are usually omitted). +Link text is either one word or a group of words enclosed by delimiters +(brackets ``[...]`` for Markdown or backticks `\`...\`_` for RST). Link text will be displayed *as is* while *link target* will be set to the anchor \[*] of Nim symbol that corresponds to link text. |