mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-06-07 04:14:19 +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

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))