Improve Markdown code blocks & start moving docs to Markdown style (#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
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
GitHub
parent
f35c9cf73d
commit
417b90a7e5
47 changed files with 341 additions and 126 deletions
638
doc/docgen.md
Normal file
638
doc/docgen.md
Normal file
|
|
@ -0,0 +1,638 @@
|
|||
===================================
|
||||
Nim DocGen Tools Guide
|
||||
===================================
|
||||
|
||||
:Author: Erik O'Leary
|
||||
:Version: |nimversion|
|
||||
|
||||
.. default-role:: code
|
||||
.. include:: rstcommon.rst
|
||||
.. contents::
|
||||
|
||||
|
||||
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
|
||||
dependencies (`import`), any top-level documentation comments (`##`), and
|
||||
exported symbols (`*`), including procedures, types, and variables.
|
||||
|
||||
=================== ====================== ============ ==============
|
||||
command runs on... input format output format
|
||||
=================== ====================== ============ ==============
|
||||
`nim doc`:cmd: documentation comments ``.nim`` ``.html`` HTML
|
||||
`nim doc2tex`:cmd: ″ ″ ``.tex`` LaTeX
|
||||
`nim jsondoc`:cmd: ″ ″ ``.json`` JSON
|
||||
`nim rst2html`:cmd: standalone rst files ``.rst`` ``.html`` HTML
|
||||
`nim rst2tex`:cmd: ″ ″ ``.tex`` LaTeX
|
||||
=================== ====================== ============ ==============
|
||||
|
||||
Quick start
|
||||
-----------
|
||||
|
||||
Generate HTML documentation for a file:
|
||||
|
||||
```cmd
|
||||
nim doc <filename>.nim
|
||||
```
|
||||
|
||||
Generate HTML documentation for a whole project:
|
||||
|
||||
```cmd
|
||||
# delete any htmldocs/*.idx file before starting
|
||||
nim doc --project --index:on --git.url:<url> --git.commit:<tag> --outdir:htmldocs <main_filename>.nim
|
||||
# this will generate html files, a theindex.html index, css and js under `htmldocs`
|
||||
# See also `--docroot` to specify a relative root.
|
||||
# to get search (dochacks.js) to work locally, you need a server otherwise
|
||||
# CORS will prevent opening file:// urls; this works:
|
||||
python3 -m http.server 7029 --directory htmldocs
|
||||
# When --outdir is omitted it defaults to $projectPath/htmldocs,
|
||||
# or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;
|
||||
# and likewise without `--project`.
|
||||
# Adding `-r` will open in a browser directly.
|
||||
```
|
||||
|
||||
Documentation Comments
|
||||
----------------------
|
||||
|
||||
Any comments which are preceded by a double-hash (`##`), are interpreted as
|
||||
documentation. Comments are parsed as RST (see `reference
|
||||
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing
|
||||
Nim module authors the ability to easily generate richly formatted
|
||||
documentation with only their well-documented code!
|
||||
Basic Markdown syntax is also supported inside the doc comments.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: nim
|
||||
type Person* = object
|
||||
## This type contains a description of a person
|
||||
name: string
|
||||
age: int
|
||||
|
||||
Outputs::
|
||||
Person* = object
|
||||
name: string
|
||||
age: int
|
||||
|
||||
This type contains a description of a person
|
||||
|
||||
Field documentation comments can be added to fields like so:
|
||||
|
||||
.. code-block:: nim
|
||||
var numValues: int ## \
|
||||
## `numValues` stores the number of values
|
||||
|
||||
Note that without the `*` following the name of the type, the documentation for
|
||||
this type would not be generated. Documentation will only be generated for
|
||||
*exported* types/procedures/etc.
|
||||
|
||||
It's recommended to always add exactly **one** space after `##` for readability
|
||||
of comments — this extra space will be cropped from the parsed comments and
|
||||
won't influence RST formatting.
|
||||
|
||||
.. note:: Generally, this baseline indentation level inside a documentation
|
||||
comment may not be 1: it can be any since it is determined by the offset
|
||||
of the first non-whitespace character in the comment.
|
||||
After that indentation **must** be consistent on the following lines of
|
||||
the same comment.
|
||||
If you still need to add an additional indentation at the very beginning
|
||||
(for RST block quote syntax) use backslash \\ before it:
|
||||
|
||||
.. code-block:: nim
|
||||
## \
|
||||
##
|
||||
## Block quote at the first line.
|
||||
##
|
||||
## Paragraph.
|
||||
|
||||
|
||||
Document Types
|
||||
==============
|
||||
|
||||
Example of Nim file input
|
||||
-------------------------
|
||||
|
||||
The following examples will generate documentation for this sample
|
||||
*Nim* module, aptly named ``doc/docgen_sample.nim``:
|
||||
|
||||
```nim file=docgen_sample.nim
|
||||
```
|
||||
|
||||
All the below commands save their output to ``htmldocs`` directory relative to
|
||||
the directory of file;
|
||||
hence the output for this sample will be in ``doc/htmldocs``.
|
||||
|
||||
HTML
|
||||
----
|
||||
|
||||
The generation of HTML documents is done via the `doc`:option: command. This command
|
||||
takes either a single ``.nim`` file, outputting a single ``.html`` file with the same
|
||||
base filename, or multiple ``.nim`` files, outputting multiple ``.html`` files and,
|
||||
optionally, an index file.
|
||||
|
||||
The `doc`:option: command:
|
||||
|
||||
```cmd
|
||||
nim doc docgen_sample.nim
|
||||
```
|
||||
|
||||
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
|
||||
compiler.
|
||||
|
||||
LaTeX
|
||||
-----
|
||||
|
||||
LaTeX files are intended to be converted to PDF, especially for offline
|
||||
reading or making hard copies. (LaTeX output is oftentimes better than
|
||||
HTML -> PDF conversion).
|
||||
|
||||
The `doc2tex`:option: command:
|
||||
|
||||
```cmd
|
||||
nim doc2tex docgen_sample.nim
|
||||
cd htmldocs
|
||||
xelatex docgen_sample.tex
|
||||
xelatex docgen_sample.tex
|
||||
# It is usually necessary to run `xelatex` 2 times (or even 3 times for
|
||||
# large documents) to get all labels generated.
|
||||
# That depends on this warning in the end of `xelatex` output:
|
||||
# LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.
|
||||
```
|
||||
|
||||
The output is ``docgen_sample.pdf``.
|
||||
|
||||
JSON
|
||||
----
|
||||
|
||||
The generation of JSON documents is done via the `jsondoc`:option: command.
|
||||
This command takes in a ``.nim`` file and outputs a ``.json`` file with
|
||||
the same base filename.
|
||||
Note that this tool is built off of the `doc`:option: command
|
||||
(previously `doc2`:option:), and contains the same information.
|
||||
|
||||
The `jsondoc`:option: command:
|
||||
|
||||
```cmd
|
||||
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: [].}"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Similarly to the old `doc`:option: command, the old `jsondoc`:option: command has been
|
||||
renamed to `jsondoc0`:option:.
|
||||
|
||||
The `jsondoc0`:option: command:
|
||||
|
||||
```cmd
|
||||
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)"
|
||||
}
|
||||
]
|
||||
|
||||
Note that the `jsondoc`:option: command outputs its JSON without pretty-printing it,
|
||||
while `jsondoc0`:option: outputs pretty-printed JSON.
|
||||
|
||||
|
||||
Referencing Nim symbols: simple documentation links
|
||||
===================================================
|
||||
|
||||
You can reference Nim identifiers from Nim documentation comments, currently
|
||||
only inside their ``.nim`` file (or inside a ``.rst`` file included from
|
||||
a ``.nim``). The point is that such links will be resolved automatically
|
||||
by `nim doc`:cmd: (or `nim jsondoc`:cmd: or `nim doc2tex`:cmd:).
|
||||
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 will be displayed *as is* while *link target* will be set to
|
||||
the anchor [*]_ of Nim symbol that corresponds to link text.
|
||||
|
||||
.. [*] anchors' format is described in `HTML anchor generation`_ section below.
|
||||
|
||||
If you have a constant:
|
||||
|
||||
```Nim
|
||||
const pi* = 3.14
|
||||
```
|
||||
|
||||
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`_
|
||||
|
||||
For routine kinds there are more options. Consider this definition:
|
||||
|
||||
```Nim
|
||||
proc foo*(a: int, b: float): string
|
||||
```
|
||||
|
||||
Generally following syntax is allowed for referencing `foo`:
|
||||
|
||||
* short (without parameters):
|
||||
|
||||
A. non-qualified::
|
||||
|
||||
foo_
|
||||
|
||||
B. qualified::
|
||||
|
||||
`proc foo`_
|
||||
|
||||
* longer variants (with parameters):
|
||||
|
||||
A. non-qualified:
|
||||
|
||||
1) specifying parameters names::
|
||||
|
||||
`foo(a, b)`_
|
||||
|
||||
2) specifying parameters types::
|
||||
|
||||
`foo(int, float)`_
|
||||
|
||||
3) specifying both names and types::
|
||||
|
||||
`foo(a: int, b: float)`_
|
||||
|
||||
4) output parameter can also be specified if you wish::
|
||||
|
||||
`foo(a: int, b: float): string`_
|
||||
|
||||
B. qualified: all 4 options above are valid.
|
||||
Particularly you can use the full format::
|
||||
|
||||
`proc foo(a: int, b: float): string`_
|
||||
|
||||
.. Tip:: Avoid cluttering your text with extraneous information by using
|
||||
one of shorter forms::
|
||||
|
||||
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::
|
||||
|
||||
`foo proc`_
|
||||
`walkDir(d: string) iterator`_
|
||||
|
||||
.. Warning:: An ambiguity in resolving documentation links may arise because of:
|
||||
|
||||
1. clash with other RST anchors
|
||||
* manually setup anchors
|
||||
* automatically set up, e.g. section names
|
||||
2. collision with other Nim symbols:
|
||||
|
||||
* routines with different parameters can exist e.g. for
|
||||
`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::
|
||||
|
||||
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.
|
||||
Use `\`proc foo\`_`:literal: or `\`iterator foo\`_`:literal: then.
|
||||
|
||||
Any ambiguity is always reported with Nim compiler warnings and an anchor
|
||||
with higher priority is selected. Manual anchors have highest
|
||||
priority, then go automatic RST anchors; then Nim-generated anchors
|
||||
(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::
|
||||
|
||||
`proc binarySearch*[T; K](a: openArray[T], key: K, cmp: proc(T, K)): int`_
|
||||
|
||||
**Limitations**:
|
||||
|
||||
1. The parameters of a nested routine type can be specified only with types
|
||||
(without parameter names, see form A.2 above).
|
||||
E.g. for this signature:
|
||||
|
||||
```Nim
|
||||
proc binarySearch*[T, K](a: openArray[T]; key: K;
|
||||
cmp: proc (x: T; y: K): int {.closure.}): int
|
||||
~~ ~~ ~~~~~
|
||||
```
|
||||
|
||||
you cannot use names underlined by `~~` so it must be referenced with
|
||||
``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)`_
|
||||
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::
|
||||
|
||||
`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.
|
||||
|
||||
* their names should be the same
|
||||
* parameters list should be given the same way, e.g. without substitutions
|
||||
between commas (,) and semicolons (;).
|
||||
|
||||
.. Note:: A bit special case is operators
|
||||
(as their signature is also defined with `\``):
|
||||
|
||||
```Nim
|
||||
func `$`(x: MyType): string
|
||||
func `[]`*[T](x: openArray[T]): T
|
||||
```
|
||||
|
||||
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 \\::
|
||||
|
||||
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`)::
|
||||
|
||||
type CopyFlag = enum
|
||||
...
|
||||
## Ref. `CopyFlag enum`_
|
||||
|
||||
Related Options
|
||||
===============
|
||||
|
||||
Project switch
|
||||
--------------
|
||||
|
||||
```cmd
|
||||
nim doc --project filename.nim
|
||||
```
|
||||
|
||||
This will recursively generate documentation of all Nim modules imported
|
||||
into the input module that belong to the Nimble package that ``filename.nim``
|
||||
belongs to. The index files and the corresponding ``theindex.html`` will
|
||||
also be generated.
|
||||
|
||||
|
||||
Index switch
|
||||
------------
|
||||
|
||||
```cmd
|
||||
nim doc --index:on filename.nim
|
||||
```
|
||||
|
||||
This will generate an index of all the exported symbols in the input Nim
|
||||
module, and put it into a neighboring file with the extension of ``.idx``. The
|
||||
index file is line-oriented (newlines have to be escaped). Each line
|
||||
represents a tab-separated record of several columns, the first two mandatory,
|
||||
the rest optional. See the `Index (idx) file format`_ section for details.
|
||||
|
||||
Once index files have been generated for one or more modules, the Nim
|
||||
compiler command `buildIndex directory` can be run to go over all the index
|
||||
files in the specified directory to generate a `theindex.html <theindex.html>`_
|
||||
file.
|
||||
|
||||
See source switch
|
||||
-----------------
|
||||
|
||||
```cmd
|
||||
nim doc --git.url:<url> filename.nim
|
||||
```
|
||||
|
||||
With the `git.url`:option: switch the *See source* hyperlink will appear below each
|
||||
documented item in your source code pointing to the implementation of that
|
||||
item on a GitHub repository.
|
||||
You can click the link to see the implementation of the item.
|
||||
|
||||
The `git.commit`:option: switch overrides the hardcoded `devel` branch in
|
||||
``config/nimdoc.cfg``.
|
||||
This is useful to link to a different branch e.g. `--git.commit:master`:option:,
|
||||
or to a tag e.g. `--git.commit:1.2.3`:option: or a commit.
|
||||
|
||||
Source URLs are generated as ``href="${url}/tree/${commit}/${path}#L${line}"``
|
||||
by default and thus compatible with GitHub but not with GitLab.
|
||||
|
||||
Similarly, `git.devel`:option: switch overrides the hardcoded `devel` branch
|
||||
for the `Edit` link which is also useful if you have a different working
|
||||
branch than `devel` e.g. `--git.devel:master`:option:.
|
||||
|
||||
Edit URLs are generated as ``href="${url}/tree/${devel}/${path}#L${line}"``
|
||||
by default.
|
||||
|
||||
You can edit ``config/nimdoc.cfg`` and modify the ``doc.item.seesrc`` value
|
||||
with a hyperlink to your own code repository.
|
||||
|
||||
In the case of Nim's own documentation, the `commit` value is just a commit
|
||||
hash to append to a formatted URL to https://github.com/nim-lang/Nim. The
|
||||
``tools/nimweb.nim`` helper queries the current git commit hash during the doc
|
||||
generation, but since you might be working on an unpublished repository, it
|
||||
also allows specifying a `githash` value in ``web/website.ini`` to force a
|
||||
specific commit in the output.
|
||||
|
||||
|
||||
Other Input Formats
|
||||
===================
|
||||
|
||||
The *Nim compiler* also has support for RST (reStructuredText) files with
|
||||
the `rst2html`:option: and `rst2tex`:option: commands. Documents like this one are
|
||||
initially written in a dialect of RST which adds support for Nim source code
|
||||
highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also
|
||||
supports highlighting of a few other languages supported by the
|
||||
`packages/docutils/highlite module <highlite.html>`_.
|
||||
|
||||
Usage:
|
||||
|
||||
```cmd
|
||||
nim rst2html docgen.rst
|
||||
```
|
||||
|
||||
Output::
|
||||
You're reading it!
|
||||
|
||||
The `rst2tex`:option: command is invoked identically to `rst2html`:option:,
|
||||
but outputs a ``.tex`` file instead of ``.html``.
|
||||
|
||||
|
||||
HTML anchor generation
|
||||
======================
|
||||
|
||||
When you run the `rst2html`:option: command, all sections in the RST document will
|
||||
get an anchor you can hyperlink to. Usually, you can guess the anchor lower
|
||||
casing the section title and replacing spaces with dashes, and in any case, you
|
||||
can get it from the table of contents. But when you run the `doc`:option:
|
||||
command to generate API documentation, some symbol get one or two anchors at
|
||||
the same time: a numerical identifier, or a plain name plus a complex name.
|
||||
|
||||
The numerical identifier is just a random number. The number gets assigned
|
||||
according to the section and position of the symbol in the file being processed
|
||||
and you should not rely on it being constant: if you add or remove a symbol the
|
||||
numbers may shuffle around.
|
||||
|
||||
The plain name of a symbol is a simplified version of its fully exported
|
||||
signature. Variables or constants have the same plain name symbol as their
|
||||
complex name. The plain name for procs, templates, and other callable types
|
||||
will be their unquoted value after removing parameters, return types, and
|
||||
pragmas. The plain name allows short and nice linking of symbols that works
|
||||
unless you have a module with collisions due to overloading.
|
||||
|
||||
If you hyperlink a plain name symbol and there are other matches on the same
|
||||
HTML file, most browsers will go to the first one. To differentiate the rest,
|
||||
you will need to use the complex name. A complex name for a callable type is
|
||||
made up of several parts:
|
||||
|
||||
(**plain symbol**)(**.type**),(**first param**)?(**,param type**)\*
|
||||
|
||||
The first thing to note is that all callable types have at least a comma, even
|
||||
if they don't have any parameters. If there are parameters, they are
|
||||
represented by their types and will be comma-separated. To the plain symbol a
|
||||
suffix may be added depending on the type of the callable:
|
||||
|
||||
============== ==============
|
||||
Callable type Suffix
|
||||
============== ==============
|
||||
`proc`, `func` *empty string*
|
||||
`macro` ``.m``
|
||||
`method` ``.e``
|
||||
`iterator` ``.i``
|
||||
`template` ``.t``
|
||||
`converter` ``.c``
|
||||
============== ==============
|
||||
|
||||
The relationship of type to suffix is made by the proc `complexName` in the
|
||||
``compiler/docgen.nim`` file. Here are some examples of complex names for
|
||||
symbols in the `system module <system.html>`_.
|
||||
|
||||
* `type SomeSignedInt = int | int8 | int16 | int32 | int64` **=>**
|
||||
`#SomeSignedInt <system.html#SomeSignedInt>`_
|
||||
* `var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}` **=>**
|
||||
`#globalRaiseHook <system.html#globalRaiseHook>`_
|
||||
* `const NimVersion = "0.0.0"` **=>**
|
||||
`#NimVersion <system.html#NimVersion>`_
|
||||
* `proc getTotalMem(): int {.rtl, raises: [], tags: [].}` **=>**
|
||||
`#getTotalMem, <system.html#getTotalMem>`_
|
||||
* `proc len[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.}` **=>**
|
||||
`#len,seq[T] <system.html#len,seq[T]>`_
|
||||
* `iterator pairs[T](a: seq[T]): tuple[key: int, val: T] {.inline.}` **=>**
|
||||
`#pairs.i,seq[T] <iterators.html#pairs.i,seq[T]>`_
|
||||
* `template newException[](exceptn: typedesc; message: string;
|
||||
parentException: ref Exception = nil): untyped` **=>**
|
||||
`#newException.t,typedesc,string,ref.Exception
|
||||
<system.html#newException.t,typedesc,string,ref.Exception>`_
|
||||
|
||||
|
||||
Index (idx) file format
|
||||
=======================
|
||||
|
||||
Files with the ``.idx`` extension are generated when you use the `Index
|
||||
switch <#related-options-index-switch>`_ along with commands to generate
|
||||
documentation from source or text files. You can programmatically generate
|
||||
indices with the `setIndexTerm()
|
||||
<rstgen.html#setIndexTerm,RstGenerator,string,string,string,string,string>`_
|
||||
and `writeIndexFile() <rstgen.html#writeIndexFile,RstGenerator,string>`_ procs.
|
||||
The purpose of `idx` files is to hold the interesting symbols and their HTML
|
||||
references so they can be later concatenated into a big index file with
|
||||
`mergeIndexes() <rstgen.html#mergeIndexes,string>`_. This section documents
|
||||
the file format in detail.
|
||||
|
||||
Index files are line-oriented and tab-separated (newline and tab characters
|
||||
have to be escaped). Each line represents a record with at least two fields
|
||||
but can have up to four (additional columns are ignored). The content of these
|
||||
columns is:
|
||||
|
||||
1. Mandatory term being indexed. Terms can include quoting according to
|
||||
Nim's rules (e.g. \`^\`).
|
||||
2. Base filename plus anchor hyperlink (e.g. ``algorithm.html#*,int,SortOrder``).
|
||||
3. Optional human-readable string to display as a hyperlink. If the value is not
|
||||
present or is the empty string, the hyperlink will be rendered
|
||||
using the term. Prefix whitespace indicates that this entry is
|
||||
not for an API symbol but for a TOC entry.
|
||||
4. Optional title or description of the hyperlink. Browsers usually display
|
||||
this as a tooltip after hovering a moment over the hyperlink.
|
||||
|
||||
The index generation tools try to differentiate between documentation
|
||||
generated from ``.nim`` files and documentation generated from ``.txt`` or
|
||||
``.rst`` files. The former are always closely related to source code and
|
||||
consist mainly of API entries. The latter are generic documents meant for
|
||||
human reading.
|
||||
|
||||
To differentiate both types (documents and APIs), the index generator will add
|
||||
to the index of documents an entry with the title of the document. Since the
|
||||
title is the topmost element, it will be added with a second field containing
|
||||
just the filename without any HTML anchor. By convention, this entry without
|
||||
anchor is the *title entry*, and since entries in the index file are added as
|
||||
they are scanned, the title entry will be the first line. The title for APIs
|
||||
is not present because it can be generated concatenating the name of the file
|
||||
to the word **Module**.
|
||||
|
||||
Normal symbols are added to the index with surrounding whitespaces removed. An
|
||||
exception to this are the table of content (TOC) entries. TOC entries are added to
|
||||
the index file with their third column having as much prefix spaces as their
|
||||
level is in the TOC (at least 1 character). The prefix whitespace helps to
|
||||
filter TOC entries from API or text symbols. This is important because the
|
||||
amount of spaces is used to replicate the hierarchy for document TOCs in the
|
||||
final index, and TOC entries found in ``.nim`` files are discarded.
|
||||
|
||||
|
||||
Additional resources
|
||||
====================
|
||||
|
||||
* `Nim Compiler User Guide <nimc.html#compiler-usage-commandminusline-switches>`_
|
||||
|
||||
* Documentation for `rst module <rst.html>`_ -- Nim RST/Markdown parser.
|
||||
|
||||
* `RST Quick Reference
|
||||
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
|
||||
|
||||
The output for HTML and LaTeX comes from the ``config/nimdoc.cfg`` and
|
||||
``config/nimdoc.tex.cfg`` configuration files. You can add and modify these
|
||||
files to your project to change the look of the docgen output.
|
||||
|
||||
You can import the `packages/docutils/rstgen module <rstgen.html>`_ in your
|
||||
programs if you want to reuse the compiler's documentation generation procs.
|
||||
Loading…
Add table
Add a link
Reference in a new issue