From 543d6b3209b4f106e3ead63d5d88fda87db64de6 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Tue, 17 Dec 2013 12:23:02 +0100 Subject: [PATCH 1/5] Replaces PDoc with var TRstGenerator for documentation. The PDoc type is a convenience internal alias. Where procs are exported only documented types should be used to avoid confusing users. --- lib/packages/docutils/rstgen.nim | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/packages/docutils/rstgen.nim b/lib/packages/docutils/rstgen.nim index 364f847ccf..b9637baa02 100644 --- a/lib/packages/docutils/rstgen.nim +++ b/lib/packages/docutils/rstgen.nim @@ -40,7 +40,7 @@ type filename*: string meta*: array[TMetaEnum, string] - PDoc = var TRstGenerator + PDoc = var TRstGenerator ## Alias to type less. proc initRstGenerator*(g: var TRstGenerator, target: TOutputTarget, config: PStringTable, filename: string, @@ -147,7 +147,7 @@ proc dispA(target: TOutputTarget, dest: var string, if target != outLatex: addf(dest, xml, args) else: addf(dest, tex, args) -proc renderRstToOut*(d: PDoc, n: PRstNode, result: var string) +proc renderRstToOut*(d: var TRstGenerator, n: PRstNode, result: var string) proc renderAux(d: PDoc, n: PRstNode, result: var string) = for i in countup(0, len(n)-1): renderRstToOut(d, n.sons[i], result) @@ -162,7 +162,7 @@ proc renderAux(d: PDoc, n: PRstNode, frmtA, frmtB: string, result: var string) = # ---------------- index handling -------------------------------------------- -proc setIndexTerm*(d: PDoc, id, term: string) = +proc setIndexTerm*(d: var TRstGenerator, id, term: string) = d.theIndex.add(term) d.theIndex.add('\t') let htmlFile = changeFileExt(extractFilename(d.filename), HtmlExt) @@ -295,7 +295,7 @@ proc renderTocEntry(d: PDoc, e: TTocEntry, result: var string) = "
  • $2
    • \n", "\\item\\label{$1_toc} $2\\ref{$1}\n", [e.refname, e.header]) -proc renderTocEntries*(d: PDoc, j: var int, lvl: int, result: var string) = +proc renderTocEntries*(d: var TRstGenerator, j: var int, lvl: int, result: var string) = var tmp = "" while j <= high(d.tocPart): var a = abs(d.tocPart[j].n.level) From f46336ae8bdddb7f3a6da4904aae18f99bc34f6f Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Wed, 18 Dec 2013 02:20:35 +0100 Subject: [PATCH 2/5] Adds missing ``code-block`` to macros' docstrings. --- lib/core/macros.nim | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/core/macros.nim b/lib/core/macros.nim index d01d4ebee4..5f0d60e5c5 100644 --- a/lib/core/macros.nim +++ b/lib/core/macros.nim @@ -268,6 +268,8 @@ proc quote*(bl: stmt, op = "``"): PNimrodNode {.magic: "QuoteAst".} ## ## Example: ## + ## .. code-block:: nimrod + ## ## macro check(ex: expr): stmt = ## # this is a simplified version of the check macro from the ## # unittest module. @@ -290,6 +292,8 @@ template emit*(e: expr[string]): stmt = ## that should be inserted verbatim in the program ## Example: ## + ## .. code-block:: nimrod + ## ## emit("echo " & '"' & "hello world".toUpper & '"') ## eval: result = e.parseStmt From e0d6a1cec18698652f1b6a4a55a749fbeb9689d1 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Wed, 18 Dec 2013 21:21:16 +0100 Subject: [PATCH 3/5] Adds some docstrings to rstgen. --- lib/packages/docutils/rstgen.nim | 91 ++++++++++++++++++++++++++++++-- 1 file changed, 87 insertions(+), 4 deletions(-) diff --git a/lib/packages/docutils/rstgen.nim b/lib/packages/docutils/rstgen.nim index b9637baa02..09c6ba8b8c 100644 --- a/lib/packages/docutils/rstgen.nim +++ b/lib/packages/docutils/rstgen.nim @@ -7,7 +7,18 @@ # distribution, for details about the copyright. # -## This module implements a generator of HTML/Latex from `reStructuredText`:idx:. +## This module implements a generator of HTML/Latex from +## `reStructuredText`:idx: (see http://docutils.sourceforge.net/rst.html for +## information on this markup syntax). You can generate HTML output through the +## convenience proc ``rstToHtml``, which provided an input string with rst +## markup returns a string with the generated HTML. The final output is meant +## to be embedded inside a full document you provide yourself, so it won't +## contain the usual ``
    `` or ```` parts. +## +## You can also create a ``TRstGenerator`` structure and populate it with the +## other lower level methods to finally build complete documents. This requires +## many options and tweaking, but you are not limited to snippets and can +## generate `LaTeX documents `_ too. import strutils, os, hashes, strtabs, rstast, rst, highlite @@ -47,6 +58,44 @@ proc initRstGenerator*(g: var TRstGenerator, target: TOutputTarget, options: TRstParseOptions, findFile: TFindFileHandler, msgHandler: TMsgHandler) = + ## Initializes a ``TRstGenerator``. + ## + ## You need to call this before using a ``TRstGenerator`` with any other + ## procs in this module. Pass a non ``nil`` ``PStringTable`` value as + ## ``config`` with parameters used by the HTML output generator. If you + ## don't know what to use, pass the results of the ``defaultConfig()`` proc. + ## The ``filename`` is symbolic and used only for error reporting, you can + ## pass any non ``nil`` string here. + ## + ## The ``TRstParseOptions``, ``TFindFileHandler`` and ``TMsgHandler`` types + ## are defined in the the `packages/docutils/rst module `_. + ## ``options`` selects the behaviour of the rst parser. + ## + ## ``findFile`` is a proc used by the rst ``include`` directive among others. + ## The purpose of this proc is to mangle or filter paths. It receives paths + ## specified in the rst document and has to return a valid path to existing + ## files or the empty string otherwise. If you pass ``nil``, a default proc + ## will be used which given a path returns the input path only if the file + ## exists. One use for this proc is to transform relative paths found in the + ## document to absolute path, useful if the rst file and the resources it + ## references are not in the same directory as the current working directory. + ## + ## The ``msgHandler`` is a proc used for user error reporting. It will be + ## called with the filename, line, col, and type of any error found during + ## parsing. If you pass ``nil``, a default message handler will be used which + ## writes the messages to the standard output. + ## + ## Example: + ## + ## .. code-block:: nimrod + ## + ## import packages/docutils/rstgen + ## + ## var gen: TRstGenerator + ## + ## gen.initRstGenerator(outHtml, defaultConfig(), + ## "filename", {}, nil, nil) + g.config = config g.target = target g.tocPart = @[] @@ -148,6 +197,18 @@ proc dispA(target: TOutputTarget, dest: var string, else: addf(dest, tex, args) proc renderRstToOut*(d: var TRstGenerator, n: PRstNode, result: var string) + ## Writes into ``result`` the rst ast ``n`` using the ``d`` configuration. + ## + ## Before using this proc you need to initialise a ``TRstGenerator`` with + ## ``initRstGenerator`` and parse a rst file with ``rstParse`` from the + ## `packages/docutils/rst module `_. Example: + ## + ## .. code-block:: nimrod + ## + ## # ...configure gen and rst vars... + ## var generatedHTML = "" + ## renderRstToOut(gen, rst, generatedHTML) + ## echo generatedHTML proc renderAux(d: PDoc, n: PRstNode, result: var string) = for i in countup(0, len(n)-1): renderRstToOut(d, n.sons[i], result) @@ -678,8 +739,26 @@ $content proc rstToHtml*(s: string, options: TRstParseOptions, config: PStringTable): string = - ## exported for *nimforum*. - + ## Converts an input rst string into embeddable HTML. + ## + ## This convenience proc parses any input string using rst markup (it doesn't + ## have to be a full document!) and returns an embeddable piece of HTML. The + ## proc is meant to be used in *online* environments without access to a + ## meaningful filesystem, and therefore rst ``include`` like directives won't + ## work. For an explanation of the ``config`` parameter see the + ## ``initRstGenerator`` proc. Example: + ## + ## .. code-block:: nimrod + ## import packages/docutils/rstgen, strtabs + ## + ## echo rstToHtml("*Hello* **world**!", {}, + ## newStringTable(modeStyleInsensitive)) + ## # --> Hello world! + ## + ## If you need to allow the rst ``include`` directive or tweak the generated + ## output you have to create your own ``TRstGenerator`` with + ## ``initRstGenerator`` and related procs. + proc myFindFile(filename: string): string = # we don't find any files in online mode: result = "" @@ -692,4 +771,8 @@ proc rstToHtml*(s: string, options: TRstParseOptions, var rst = rstParse(s, filen, 0, 1, dummyHasToc, options) result = "" renderRstToOut(d, rst, result) - + + +when isMainModule: + echo rstToHtml("*Hello* **world**!", {}, + newStringTable(modeStyleInsensitive)) From 9f8db3ae542ab3dc8d18e5859b06bfa95b4e12ce Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Wed, 18 Dec 2013 21:25:49 +0100 Subject: [PATCH 4/5] Updates idetools docs after changes by #743. --- doc/idetools.txt | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/doc/idetools.txt b/doc/idetools.txt index fdc4ebde67..f2e690b0f8 100644 --- a/doc/idetools.txt +++ b/doc/idetools.txt @@ -522,21 +522,6 @@ At the moment idetools support is still in development so the test suite is not integrated with the main test suite and you have to run it manually. First you have to compile the tester:: - $ cd my/nimrod/checkout - $ nimrod c tests/tester.nim - -Running the tester without parameters will display some options. -To run the caas test suite (and other special tests) you need to -use the `special` command. You need to run this command from the -root of the checkout or it won't be able to open the required files:: - - $ ./tests/tester special - -However this is a roundabout way of running the test suite. You can -also compile and run ``tests/caasdriver.nim`` manually. In fact, -running it manually will allow you to specify special parameters -too. Example:: - $ cd my/nimrod/checkout/tests $ nimrod c caasdriver.nim From 7177e0f69877d9cde61a14e4df6a2478d35503e4 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Wed, 18 Dec 2013 23:32:39 +0100 Subject: [PATCH 5/5] Adds docstring to macros.newIdentDefs. --- lib/core/macros.nim | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/lib/core/macros.nim b/lib/core/macros.nim index 5f0d60e5c5..7caf4c5537 100644 --- a/lib/core/macros.nim +++ b/lib/core/macros.nim @@ -478,6 +478,34 @@ proc newDotExpr*(a, b: PNimrodNode): PNimrodNode {.compileTime.} = proc newIdentDefs*(name, kind: PNimrodNode; default = newEmptyNode()): PNimrodNode {.compileTime.} = + ## Creates a new ``nnkIdentDefs`` node of a specific kind and value. + ## + ## ``nnkIdentDefs`` need to have at least three children, but they can have + ## more: first comes a list of identifiers followed by a type and value + ## nodes. This helper proc creates a three node subtree, the first subnode + ## being a single identifier name. Both the ``kind`` node and ``default`` + ## (value) nodes may be empty depending on where the ``nnkIdentDefs`` + ## appears: tuple or object definitions will have an empty ``default`` node, + ## ``let`` or ``var`` blocks may have an empty ``kind`` node if the + ## identifier is being assigned a value. Example: + ## + ## .. code-block:: nimrod + ## + ## var varSection = newNimNode(nnkVarSection).add( + ## newIdentDefs(ident("a"), ident("string")), + ## newIdentDefs(ident("b"), newEmptyNode(), newLit(3))) + ## # --> var + ## # a: string + ## # b = 3 + ## + ## If you need to create multiple identifiers you need to use the lower level + ## ``newNimNode``: + ## + ## .. code-block:: nimrod + ## + ## result = newNimNode(nnkIdentDefs).add( + ## ident("a"), ident("b"), ident("c"), ident("string"), + ## newStrLitNode("Hello")) newNimNode(nnkIdentDefs).add(name, kind, default) proc newNilLit*(): PNimrodNode {.compileTime.} =