From e0fc07df89a2bc9a9472b08c4003be7b2ff6498b Mon Sep 17 00:00:00 2001 From: Erik O'Leary Date: Tue, 31 Dec 2013 19:37:20 -0600 Subject: [PATCH 1/6] Added docgen documentation --- doc/docgen.txt | 182 +++++++++++++++++++++ doc/docgen_samples/sample.html | 282 ++++++++++++++++++++++++++++++++ doc/docgen_samples/sample2.html | 282 ++++++++++++++++++++++++++++++++ 3 files changed, 746 insertions(+) create mode 100644 doc/docgen.txt create mode 100644 doc/docgen_samples/sample.html create mode 100644 doc/docgen_samples/sample2.html diff --git a/doc/docgen.txt b/doc/docgen.txt new file mode 100644 index 0000000000..998cde8391 --- /dev/null +++ b/doc/docgen.txt @@ -0,0 +1,182 @@ +=================================== + Nimrod DocGen Tools Guide +=================================== + +:Author: Erik O'Leary +:Version: |nimrodversion| + +.. contents:: + + +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. + + +Documentation Comments +---------------------- +Any comments which are preceeded by a double-hash (##), are interpreted as documentation. +Comments are parsed as RST +(see `reference `_), 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 `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 `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 `_. The ``rst2tex`` command is invoked identically to +``rst2html``, but outputs a .tex file instead of .html. + + +Additional Resources +========= + +`Nimrod Compiler User Guide `_ + +`RST Quick Reference `_ diff --git a/doc/docgen_samples/sample.html b/doc/docgen_samples/sample.html new file mode 100644 index 0000000000..4efa40905e --- /dev/null +++ b/doc/docgen_samples/sample.html @@ -0,0 +1,282 @@ + + + + + + +Module sample + + + + +
+

Module sample

+ +
+This module is a sample. + +
+

Procs

+
+
proc helloWorld*(times: int)
+
+Takes an integer and outputs as many "hello world!"s +
+ +
+ +
+ +Generated: 2013-12-21 11:45:42 UTC +
+ + diff --git a/doc/docgen_samples/sample2.html b/doc/docgen_samples/sample2.html new file mode 100644 index 0000000000..3ff5e27e54 --- /dev/null +++ b/doc/docgen_samples/sample2.html @@ -0,0 +1,282 @@ + + + + + + +Module sample + + + + +
+

Module sample

+ +
+This module is a sample. + +
+

Procs

+
+
proc helloWorld(times: int) {.raises: [], tags: [].}
+
+Takes an integer and outputs as many "hello world!"s +
+ +
+ +
+ +Generated: 2013-12-21 11:45:52 UTC +
+ + From 0b6c9d7d75db7b3a9b93c465ba8a99c559fc305c Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 6 Jan 2014 13:18:27 +0100 Subject: [PATCH 2/6] Fixes two minor typos. --- doc/docgen.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/docgen.txt b/doc/docgen.txt index 998cde8391..e287e48251 100644 --- a/doc/docgen.txt +++ b/doc/docgen.txt @@ -13,14 +13,14 @@ 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 +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 preceeded by a double-hash (##), are interpreted as documentation. +Any comments which are preceded by a double-hash (##), are interpreted as documentation. Comments are parsed as RST (see `reference `_), providing Nimrod module authors the ability to easily generate richly formatted documentation with only From fd6bb131b87c740e843f1615af85d217018fe9c7 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 6 Jan 2014 13:22:44 +0100 Subject: [PATCH 3/6] Reformats text to fit width of 80 columns. --- doc/docgen.txt | 90 ++++++++++++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 40 deletions(-) diff --git a/doc/docgen.txt b/doc/docgen.txt index e287e48251..0e897dcd59 100644 --- a/doc/docgen.txt +++ b/doc/docgen.txt @@ -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 `_), 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 +`_), 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 `_. 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 `_. +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 `_. 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 `_. +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 `_. The ``rst2tex`` command is invoked identically to -``rst2html``, but outputs a .tex file instead of .html. +The input can be viewed here `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 `_ -`RST Quick Reference `_ +`RST Quick Reference +`_ From 5844697aa6875b03fb4b7df4ccbcb824a3c1e1c1 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 6 Jan 2014 13:31:21 +0100 Subject: [PATCH 4/6] Adds docgen to list of documentation to build. --- web/nimrod.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/web/nimrod.ini b/web/nimrod.ini index f10a4b2f21..b3e8594459 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" From 91ae5a3585d93c94d1dba45c9c607496945bce0e Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 6 Jan 2014 13:40:11 +0100 Subject: [PATCH 5/6] Adds some cross references to docgen manual. --- doc/docgen.txt | 12 ++++++------ doc/nimrodc.txt | 7 +++++++ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/doc/docgen.txt b/doc/docgen.txt index 0e897dcd59..2ef06e578f 100644 --- a/doc/docgen.txt +++ b/doc/docgen.txt @@ -11,12 +11,12 @@ 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`:idx: 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 diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt index f5fbf3ebbe..52e0a6eaf4 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 `_. + Nimrod idetools integration =========================== From 2ed7849921f0413c175094ff15b1cf71d931ed1c Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 6 Jan 2014 14:55:03 +0100 Subject: [PATCH 6/6] Transforms docgen sample to be generated from source. --- doc/docgen.txt | 4 +- doc/docgen_sample.nim | 12 ++ doc/docgen_samples/sample.html | 282 -------------------------------- doc/docgen_samples/sample2.html | 282 -------------------------------- tools/nimweb.nim | 14 ++ 5 files changed, 28 insertions(+), 566 deletions(-) create mode 100644 doc/docgen_sample.nim delete mode 100644 doc/docgen_samples/sample.html delete mode 100644 doc/docgen_samples/sample2.html diff --git a/doc/docgen.txt b/doc/docgen.txt index 2ef06e578f..acd09f2eb1 100644 --- a/doc/docgen.txt +++ b/doc/docgen.txt @@ -97,7 +97,7 @@ Partial Output:: proc helloWorld*(times: int) ... -Output can be viewed in full here `sample.html `_. +Output can be viewed in full here: `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. @@ -110,7 +110,7 @@ Partial Output:: proc helloWorld(times: int) {.raises: [], tags: [].} ... -The full output can be seen here `sample2.html `_. +The full output can be seen here: `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 diff --git a/doc/docgen_sample.nim b/doc/docgen_sample.nim new file mode 100644 index 0000000000..8759931873 --- /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/docgen_samples/sample.html b/doc/docgen_samples/sample.html deleted file mode 100644 index 4efa40905e..0000000000 --- a/doc/docgen_samples/sample.html +++ /dev/null @@ -1,282 +0,0 @@ - - - - - - -Module sample - - - - -
-

Module sample

- -
-This module is a sample. - -
-

Procs

-
-
proc helloWorld*(times: int)
-
-Takes an integer and outputs as many "hello world!"s -
- -
- -
- -Generated: 2013-12-21 11:45:42 UTC -
- - diff --git a/doc/docgen_samples/sample2.html b/doc/docgen_samples/sample2.html deleted file mode 100644 index 3ff5e27e54..0000000000 --- a/doc/docgen_samples/sample2.html +++ /dev/null @@ -1,282 +0,0 @@ - - - - - - -Module sample - - - - -
-

Module sample

- -
-This module is a sample. - -
-

Procs

-
-
proc helloWorld(times: int) {.raises: [], tags: [].}
-
-Takes an integer and outputs as many "hello world!"s -
- -
- -
- -Generated: 2013-12-21 11:45:52 UTC -
- - diff --git a/tools/nimweb.nim b/tools/nimweb.nim index c5d510eacc..0e519b4b82 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")