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

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
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 Introduction
============ ============
This document describes the documentation generation tools built into the *Nimrod compiler*, This document describes the documentation generation tools built into the
which can generate HTML and JSON output from input .nim files and projects, as well as HTML *Nimrod compiler*, which can generate HTML and JSON output from input .nim
and LaTeX from input RST (reStructuredText) files. The output documentation will include files and projects, as well as HTML and LaTeX from input RST (reStructuredText)
module dependencies (``import``), any top-level documentation comments (##), and exported files. The output documentation will include module dependencies (``import``),
symbols (*), including procedures, types, and variables. any top-level documentation comments (##), and exported symbols (*), including
procedures, types, and variables.
Documentation Comments Documentation Comments
---------------------- ----------------------
Any comments which are preceded by a double-hash (##), are interpreted as documentation.
Comments are parsed as RST Any comments which are preceded by a double-hash (##), are interpreted as
(see `reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing documentation. Comments are parsed as RST (see `reference
Nimrod module authors the ability to easily generate richly formatted documentation with only <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing
their well-documented code. Nimrod module authors the ability to easily generate richly formatted
documentation with only their well-documented code.
Example: Example:
@ -47,8 +49,9 @@ Field documentation comments can be added to fields like so:
var numValues: int ## \ var numValues: int ## \
## `numValues` stores the number of values ## `numValues` stores the number of values
Note that without the `*` following the name of the type, the documentation for this type Note that without the `*` following the name of the type, the documentation for
would not be generated. Documentation will only be generated for *exported* types/procedures/etc. this type would not be generated. Documentation will only be generated for
*exported* types/procedures/etc.
Nimrod file input Nimrod file input
@ -80,10 +83,11 @@ Document Types
HTML 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, Generation of HTML documents is done via both the ``doc`` and ``doc2``
or multiple .nim files, outputting multiple .html files and, optionally, commands. These command take either a single .nim file, outputting a single
an index file. .html file with the same base filename, or multiple .nim files, outputting
multiple .html files and, optionally, an index file.
The ``doc`` command:: The ``doc`` command::
nimrod doc sample nimrod doc sample
@ -93,9 +97,10 @@ Partial Output::
proc helloWorld*(times: int) proc helloWorld*(times: int)
... ...
Output can be viewed in full here `sample.html <docgen_samples/sample.html>`_. The next command, Output can be viewed in full here `sample.html <docgen_samples/sample.html>`_.
called ``doc2``, is very similar to the ``doc`` command, but will be run after the The next command, called ``doc2``, is very similar to the ``doc`` command, but
compiler performs semantic checking on the input nimrod module(s), which allows it to process macros. will be run after the compiler performs semantic checking on the input nimrod
module(s), which allows it to process macros.
The ``doc2`` command:: The ``doc2`` command::
nimrod doc2 sample nimrod doc2 sample
@ -105,19 +110,21 @@ Partial Output::
proc helloWorld(times: int) {.raises: [], tags: [].} 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 The full output can be seen here `sample2.html <docgen_samples/sample2.html>`_.
extracted additional information provided to it by the compiler beyond what the ``doc`` As you can see, the tool has extracted additional information provided to it by
command provides, such as pragmas attached implicitly by the compiler. This type of information the compiler beyond what the ``doc`` command provides, such as pragmas attached
is not available from looking at the AST (Abstract Syntax Tree) prior to semantic checking, implicitly by the compiler. This type of information is not available from
as the ``doc`` command does. looking at the AST (Abstract Syntax Tree) prior to semantic checking, as the
``doc`` command does.
JSON 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 Generation of JSON documents is done via the ``jsondoc`` command. This command
tool is built off of the ``doc`` command, and therefore is performed before semantic takes in a .nim file, and outputs a .json file with the same base filename.
checking. Note that this tool is built off of the ``doc`` command, and therefore is
performed before semantic checking.
The ``jsondoc`` command:: The ``jsondoc`` command::
nimrod jsondoc sample nimrod jsondoc sample
@ -143,26 +150,27 @@ Related Options
:: ::
nimrod doc2 --project sample nimrod doc2 --project sample
This will recursively generate documentation of all nimrod modules imported into the input module, This will recursively generate documentation of all nimrod modules imported
including system modules. Be careful with this command, as it may end up sprinkling html files all into the input module, including system modules. Be careful with this command,
over your filesystem! as it may end up sprinkling html files all over your filesystem!
``--index`` switch ``--index`` switch
:: ::
nimrod doc2 --index:on sample nimrod doc2 --index:on sample
This will generate an index of all the exported symbols in the input Nimrod module, and put it into This will generate an index of all the exported symbols in the input Nimrod
a neighboring file with the extension of `.idx`. module, and put it into a neighboring file with the extension of `.idx`.
Other Input Formats Other Input Formats
=================== ===================
The *Nimrod compiler* also has support for RST (reStructuredText) files with the ``rst2html`` and ``rst2tex`` The *Nimrod compiler* also has support for RST (reStructuredText) files with
commands. Documents like this one are initially written in a dialect of RST which adds support for nimrod the ``rst2html`` and ``rst2tex`` commands. Documents like this one are
sourcecode highlighting with the ``.. code-block:: nimrod`` prefix. ``code-block`` also supports highlighting initially written in a dialect of RST which adds support for nimrod sourcecode
of C++ and some other c-like languages. highlighting with the ``.. code-block:: nimrod`` prefix. ``code-block`` also
supports highlighting of C++ and some other c-like languages.
Usage:: Usage::
nimrod rst2html docgen.txt nimrod rst2html docgen.txt
@ -170,8 +178,9 @@ Usage::
Output:: Output::
You're reading it! You're reading it!
The input can be viewed here `docgen.txt <docgen.txt>`_. The ``rst2tex`` command is invoked identically to The input can be viewed here `docgen.txt <docgen.txt>`_. The ``rst2tex``
``rst2html``, but outputs a .tex file instead of .html. command is invoked identically to ``rst2html``, but outputs a .tex file instead
of .html.
Additional Resources Additional Resources
@ -179,4 +188,5 @@ Additional Resources
`Nimrod Compiler User Guide <nimrodc.html#command-line-switches>`_ `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>`_