1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
===================================
Nimrod DocGen Tools Guide
===================================
:Author: Erik O'Leary
:Version: |nimrodversion|
.. contents::
Introduction
============
This document describes the `documentation generation tools`:idx: built into
the `Nimrod compiler <nimrodc.html>`_, which can generate HTML 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 module
dependencies (``import``), any top-level documentation comments (##), and
exported symbols (*), including procedures, types, and variables.
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
Nimrod module authors the ability to easily generate richly formatted
documentation with only their well-documented code.
Example:
.. code-block:: nimrod
type TPerson* = object
## This type contains a description of a person
name: string
age: int
Outputs::
TPerson* = 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:: nimrod
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.
Nimrod file input
-----------------
The following examples will generate documentation for the below contrived
*Nimrod* module, aptly named 'sample.nim'
sample.nim:
.. code-block:: nimrod
## This module is a sample.
import strutils
proc helloWorld*(times: int) =
## Takes an integer and outputs
## as many "hello world!"s
for i in 0 .. times-1:
echo "hello world!"
helloWorld(5)
Document Types
==============
HTML
----
Generation of HTML documents is done via both the ``doc`` and ``doc2``
commands. These command take 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`` command::
nimrod doc sample
Partial Output::
...
proc helloWorld*(times: int)
...
Output can be viewed in full here: `docgen_sample.html <docgen_sample.html>`_.
The next command, called ``doc2``, is very similar to the ``doc`` command, but
will be run after the compiler performs semantic checking on the input nimrod
module(s), which allows it to process macros.
The ``doc2`` command::
nimrod doc2 sample
Partial Output::
...
proc helloWorld(times: int) {.raises: [], tags: [].}
...
The full output can be seen here: `docgen_sample2.html <docgen_sample2.html>`_.
As you can see, the tool has extracted additional information provided to it by
the compiler beyond what the ``doc`` command provides, such as pragmas attached
implicitly by the compiler. This type of information is not available from
looking at the AST (Abstract Syntax Tree) prior to semantic checking, as the
``doc`` command does.
JSON
----
Generation of JSON documents is done via the ``jsondoc`` 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`` command, and therefore is
performed before semantic checking.
The ``jsondoc`` command::
nimrod jsondoc sample
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)"
}
]
Related Options
===============
``--project`` switch
::
nimrod doc2 --project sample
This will recursively generate documentation of all nimrod modules imported
into the input module, including system modules. Be careful with this command,
as it may end up sprinkling html files all over your filesystem!
``--index`` switch
::
nimrod doc2 --index:on sample
This will generate an index of all the exported symbols in the input Nimrod
module, and put it into a neighboring file with the extension of `.idx`.
Other Input Formats
===================
The *Nimrod compiler* also has support for RST (reStructuredText) files with
the ``rst2html`` and ``rst2tex`` commands. Documents like this one are
initially written in a dialect of RST which adds support for nimrod sourcecode
highlighting with the ``.. code-block:: nimrod`` prefix. ``code-block`` also
supports highlighting of C++ and some other c-like languages.
Usage::
nimrod rst2html docgen.txt
Output::
You're reading it!
The input can be viewed here `docgen.txt <docgen.txt>`_. The ``rst2tex``
command is invoked identically to ``rst2html``, but outputs a .tex file instead
of .html.
Additional Resources
=========
`Nimrod Compiler User Guide <nimrodc.html#command-line-switches>`_
`RST Quick Reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
|