diff options
| -rw-r--r-- | doc/docgen.txt | 192 | ||||
| -rw-r--r-- | doc/docgen_sample.nim | 12 | ||||
| -rw-r--r-- | doc/nimrodc.txt | 7 | ||||
| -rw-r--r-- | tools/nimweb.nim | 14 | ||||
| -rw-r--r-- | web/nimrod.ini | 2 |
5 files changed, 226 insertions, 1 deletions
diff --git a/doc/docgen.txt b/doc/docgen.txt new file mode 100644 index 000000000..acd09f2eb --- /dev/null +++ b/doc/docgen.txt @@ -0,0 +1,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>`_ diff --git a/doc/docgen_sample.nim b/doc/docgen_sample.nim new file mode 100644 index 000000000..875993187 --- /dev/null +++ b/doc/docgen_sample.nim @@ -0,0 +1,12 @@ +## 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) diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt index f5fbf3ebb..52e0a6eaf 100644 --- a/doc/nimrodc.txt +++ b/doc/nimrodc.txt @@ -538,6 +538,13 @@ on Linux:: nimrod c --dynlibOverride:lua --passL:liblua.lib program.nim +Nimrod documentation tools +========================== + +Nimrod provides the `doc`:idx: and `doc2`:idx: commands to generate HTML +documentation from ``.nim`` source files. Only exported symbols will appear in +the output. For more details `see the docgen documentation <docgen.html>`_. + Nimrod idetools integration =========================== diff --git a/tools/nimweb.nim b/tools/nimweb.nim index 84b790248..56d6bcadb 100644 --- a/tools/nimweb.nim +++ b/tools/nimweb.nim @@ -204,6 +204,18 @@ proc exec(cmd: string) = echo(cmd) if os.execShellCmd(cmd) != 0: quit("external program failed") +proc buildDocSamples(c: var TConfigData, destPath: string) = + ## Special case documentation sample proc. + ## + ## The docgen sample needs to be generated twice with different commands, so + ## it didn't make much sense to integrate into the existing generic + ## documentation builders. + const src = "doc"/"docgen_sample.nim" + Exec("nimrod doc $# -o:$# $#" % + [c.nimrodArgs, destPath / "docgen_sample.html", src]) + Exec("nimrod doc2 $# -o:$# $#" % + [c.nimrodArgs, destPath / "docgen_sample2.html", src]) + proc buildDoc(c: var TConfigData, destPath: string) = # call nim for the documentation: for d in items(c.doc): @@ -352,7 +364,9 @@ proc main(c: var TConfigData) = copyDir("web/assets", "web/upload/assets") buildNewsRss(c, "web/upload") buildAddDoc(c, "web/upload") + buildDocSamples(c, "web/upload") buildDoc(c, "web/upload") + buildDocSamples(c, "doc") buildDoc(c, "doc") buildPdfDoc(c, "doc") diff --git a/web/nimrod.ini b/web/nimrod.ini index 6942f20a9..9af3bc226 100644 --- a/web/nimrod.ini +++ b/web/nimrod.ini @@ -37,7 +37,7 @@ UNIX. We don't believe this to be a coincidence. - Jeremy S. Anderson.""" [Documentation] doc: "endb;intern;apis;lib;manual;tut1;tut2;nimrodc;overview;filters;trmacros" -doc: "tools;c2nim;niminst;nimgrep;gc;estp;idetools" +doc: "tools;c2nim;niminst;nimgrep;gc;estp;idetools;docgen" pdf: "manual;lib;tut1;tut2;nimrodc;c2nim;niminst;gc" srcdoc2: "system.nim;impure/graphics;wrappers/sdl" srcdoc2: "core/macros;pure/marshal;core/typeinfo;core/unsigned" |