mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-06-05 03:14:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reformats text to fit width of 80 columns.

Browse Source
This commit is contained in:
Grzegorz Adam Hankiewicz
2014-01-06 13:22:44 +01:00
parent 0b6c9d7d75
commit fd6bb131b8
1 changed files with 50 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
doc/docgen.txt
View File

@@ -11,20 +11,22 @@
Introduction
============
This document describes the documentation generation tools built into the *Nimrod compiler*,
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.
This document describes the documentation generation tools built into the
*Nimrod compiler*, 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.
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:
@@ -47,8 +49,9 @@ Field documentation comments can be added to fields like so:
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.
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
@@ -80,10 +83,11 @@ 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.
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
@@ -93,9 +97,10 @@ Partial Output::
proc helloWorld*(times: int)
...
Output can be viewed in full here `sample.html <docgen_samples/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.
Output can be viewed in full here `sample.html <docgen_samples/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
@@ -105,19 +110,21 @@ Partial Output::
proc helloWorld(times: int) {.raises: [], tags: [].}
...
The full output can be seen here `sample2.html <docgen_samples/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.
The full output can be seen here `sample2.html <docgen_samples/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.
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
@@ -143,26 +150,27 @@ Related Options
::
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!
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`.
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.
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
@@ -170,8 +178,9 @@ Usage::
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.
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
@@ -179,4 +188,5 @@ Additional Resources
`Nimrod Compiler User Guide <nimrodc.html#command-line-switches>`_
`RST Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
`RST Quick Reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_