mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2025-12-28 17:04:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #764 from gradha/pr_doc_improvements

Browse Source 
Documentation improvements
This commit is contained in:
Andreas Rumpf
2013-12-20 13:02:44 -08:00
parent f391bfed93 7177e0f698
commit 2f7119e9bb
3 changed files with 123 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
doc/idetools.txt
View File

@@ -527,21 +527,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

32
lib/core/macros.nim
View File

@@ -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
@@ -474,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.} =

99
lib/packages/docutils/rstgen.nim
View File

@@ -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 ``<header>`` or ``<body>`` 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 <https://en.wikipedia.org/wiki/LaTeX>`_ too.
import strutils, os, hashes, strtabs, rstast, rst, highlite
@@ -40,13 +51,51 @@ 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,
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 <rst.html>`_.
## ``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 = @[]
@@ -147,7 +196,19 @@ 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)
## 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 <rst.html>`_. 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)
@@ -162,7 +223,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 +356,7 @@ proc renderTocEntry(d: PDoc, e: TTocEntry, result: var string) =
"<li><a class=\"reference\" id=\"$1_toc\" href=\"#$1\">$2</a></li>\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)
@@ -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))
## # --> <em>Hello</em> <strong>world</strong>!
##
## 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))