Nimrod renamed to Nim
This commit is contained in:
Araq
parent
c95e47216f
commit
3ea6446900
30 changed files with 379 additions and 379 deletions
|
|
@ -1,9 +1,9 @@
|
|||
===================================
|
||||
Nimrod DocGen Tools Guide
|
||||
Nim DocGen Tools Guide
|
||||
===================================
|
||||
|
||||
:Author: Erik O'Leary
|
||||
:Version: |nimrodversion|
|
||||
:Version: |nimversion|
|
||||
|
||||
.. contents::
|
||||
|
||||
|
|
@ -12,7 +12,7 @@ Introduction
|
|||
============
|
||||
|
||||
This document describes the `documentation generation tools`:idx: built into
|
||||
the `Nimrod compiler <nimrodc.html>`_, which can generate HTML and JSON output
|
||||
the `Nim compiler <nimc.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
|
||||
|
|
@ -25,12 +25,12 @@ 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
|
||||
Nim module authors the ability to easily generate richly formatted
|
||||
documentation with only their well-documented code.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: nimrod
|
||||
.. code-block:: nim
|
||||
type TPerson* = object
|
||||
## This type contains a description of a person
|
||||
name: string
|
||||
|
|
@ -45,7 +45,7 @@ This type contains a description of a person
|
|||
|
||||
Field documentation comments can be added to fields like so:
|
||||
|
||||
.. code-block:: nimrod
|
||||
.. code-block:: nim
|
||||
var numValues: int ## \
|
||||
## `numValues` stores the number of values
|
||||
|
||||
|
|
@ -54,15 +54,15 @@ this type would not be generated. Documentation will only be generated for
|
|||
*exported* types/procedures/etc.
|
||||
|
||||
|
||||
Nimrod file input
|
||||
Nim file input
|
||||
-----------------
|
||||
|
||||
The following examples will generate documentation for the below contrived
|
||||
*Nimrod* module, aptly named 'sample.nim'
|
||||
*Nim* module, aptly named 'sample.nim'
|
||||
|
||||
sample.nim:
|
||||
|
||||
.. code-block:: nimrod
|
||||
.. code-block:: nim
|
||||
## This module is a sample.
|
||||
|
||||
import strutils
|
||||
|
|
@ -90,7 +90,7 @@ commands. These command take either a single .nim file, outputting a single
|
|||
multiple .html files and, optionally, an index file.
|
||||
|
||||
The ``doc`` command::
|
||||
nimrod doc sample
|
||||
nim doc sample
|
||||
|
||||
Partial Output::
|
||||
...
|
||||
|
|
@ -99,11 +99,11 @@ Partial Output::
|
|||
|
||||
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
|
||||
will be run after the compiler performs semantic checking on the input nim
|
||||
module(s), which allows it to process macros.
|
||||
|
||||
The ``doc2`` command::
|
||||
nimrod doc2 sample
|
||||
nim doc2 sample
|
||||
|
||||
Partial Output::
|
||||
...
|
||||
|
|
@ -127,7 +127,7 @@ Note that this tool is built off of the ``doc`` command, and therefore is
|
|||
performed before semantic checking.
|
||||
|
||||
The ``jsondoc`` command::
|
||||
nimrod jsondoc sample
|
||||
nim jsondoc sample
|
||||
|
||||
Output::
|
||||
[
|
||||
|
|
@ -150,9 +150,9 @@ Project switch
|
|||
--------------
|
||||
|
||||
::
|
||||
nimrod doc2 --project filename.nim
|
||||
nim doc2 --project filename.nim
|
||||
|
||||
This will recursively generate documentation of all nimrod modules imported
|
||||
This will recursively generate documentation of all nim 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!
|
||||
|
||||
|
|
@ -161,15 +161,15 @@ Index switch
|
|||
------------
|
||||
|
||||
::
|
||||
nimrod doc2 --index:on filename.nim
|
||||
nim doc2 --index:on filename.nim
|
||||
|
||||
This will generate an index of all the exported symbols in the input Nimrod
|
||||
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 Nimrod
|
||||
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.
|
||||
|
|
@ -178,7 +178,7 @@ See source switch
|
|||
-----------------
|
||||
|
||||
::
|
||||
nimrod doc2 --docSeeSrcUrl:txt filename.nim
|
||||
nim doc2 --docSeeSrcUrl:txt filename.nim
|
||||
|
||||
When you pass the ``docSeeSrcUrl`` switch to docgen, after each documented item
|
||||
in your source code the hyper link *See source* will appear pointing to the
|
||||
|
|
@ -191,25 +191,25 @@ hyper link to your own code repository. As you will see by the comments in that
|
|||
file, the value ``txt`` passed on the command line will be used in the HTML
|
||||
template along others like ``$path`` and ``$line``.
|
||||
|
||||
In the case of Nimrod's own documentation, the ``txt`` value is just a commit
|
||||
hash to append to a formatted URL to https://github.com/Araq/Nimrod. The
|
||||
In the case of Nim's own documentation, the ``txt`` value is just a commit
|
||||
hash to append to a formatted URL to https://github.com/Araq/Nim. The
|
||||
``tools/nimweb.nim`` helper queries the current git commit hash during doc
|
||||
generation, but since you might be working on an unpublished repository, it
|
||||
also allows specifying a ``githash`` value in ``web/nimrod.ini`` to force a
|
||||
also allows specifying a ``githash`` value in ``web/nim.ini`` to force a
|
||||
specific commit in the output.
|
||||
|
||||
|
||||
Other Input Formats
|
||||
===================
|
||||
|
||||
The *Nimrod compiler* also has support for RST (reStructuredText) files with
|
||||
The *Nim 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
|
||||
initially written in a dialect of RST which adds support for nim sourcecode
|
||||
highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also
|
||||
supports highlighting of C++ and some other c-like languages.
|
||||
|
||||
Usage::
|
||||
nimrod rst2html docgen.txt
|
||||
nim rst2html docgen.txt
|
||||
|
||||
Output::
|
||||
You're reading it!
|
||||
|
|
@ -272,8 +272,8 @@ symbols in the `system module <system.html>`_.
|
|||
`#TSignedInt <system.html#TSignedInt>`_
|
||||
* ``var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}`` **=>**
|
||||
`#globalRaiseHook <system.html#globalRaiseHook>`_
|
||||
* ``const NimrodVersion = "0.0.0"`` **=>**
|
||||
`#NimrodVersion <system.html#NimrodVersion>`_
|
||||
* ``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.}`` **=>**
|
||||
|
|
@ -304,7 +304,7 @@ 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
|
||||
Nimrod's rules (eg. \`^\` like in `the actors module
|
||||
Nim's rules (eg. \`^\` like in `the actors module
|
||||
<actors.html#^,ptr.TChannel[T]>`_).
|
||||
2. Base filename plus anchor hyper link (eg.
|
||||
``algorithm.html#*,int,TSortOrder``).
|
||||
|
|
@ -342,7 +342,7 @@ final index, and TOC entries found in ``.nim`` files are discarded.
|
|||
Additional resources
|
||||
====================
|
||||
|
||||
`Nimrod Compiler User Guide <nimrodc.html#command-line-switches>`_
|
||||
`Nim Compiler User Guide <nimc.html#command-line-switches>`_
|
||||
|
||||
`RST Quick Reference
|
||||
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue