#
#
# The Nimrod Compiler
# (c) Copyright 2012 Andreas Rumpf
#
# See the file "copying.txt", included in this
# distribution, for details about the copyright.
#
# This is the documentation generator. It is currently pretty simple: No
# semantic checking is done for the code. Cross-references are generated
# by knowing how the anchors are going to be named.
import
ast, astalgo, strutils, hashes, options, nversion, msgs, os, ropes, idents,
wordrecg, math, syntaxes, renderer, lexer, rst, times, highlite, importer
proc CommandDoc*()
proc CommandRst2Html*()
proc CommandRst2TeX*()
# implementation
type
TTocEntry{.final.} = object
n*: PRstNode
refname*, header*: PRope
TSections = array[TSymKind, PRope]
TMetaEnum = enum
metaNone, metaTitle, metaSubtitle, metaAuthor, metaVersion
TDocumentor{.final.} = object # contains a module's documentation
filename*: string # filename of the source file; without extension
basedir*: string # base directory (where to put the documentation)
modDesc*: PRope # module description
id*: int # for generating IDs
splitAfter*: int # split too long entries in the TOC
tocPart*: seq[TTocEntry]
hasToc*: bool
toc*, section*: TSections
indexFile*, theIndex*: PRstNode
indexValFilename*: string
indent*, verbatim*: int # for code generation
meta*: array[TMetaEnum, PRope]
PDoc = ref TDocumentor
var splitter: string = "<wbr />"
proc findIndexNode(n: PRstNode): PRstNode =
if n == nil:
result = nil
elif n.kind == rnIndex:
result = n.sons[2]
if result == nil:
result = newRstNode(rnDefList)
n.sons[2] = result
elif result.kind == rnInner:
result = result.sons[0]
else:
result = nil
for i in countup(0, rsonsLen(n) - 1):
result = findIndexNode(n.sons[i])
if result != nil: return
proc initIndexFile(d: PDoc) =
var
h: PRstNode
dummyHasToc: bool
if gIndexFile.len == 0: return
gIndexFile = addFileExt(gIndexFile, "txt")
d.indexValFilename = changeFileExt(extractFilename(d.filename), HtmlExt)
if ExistsFile(gIndexFile):
d.indexFile = rstParse(readFile(gIndexFile), false, gIndexFile, 0, 1,
dummyHasToc)
d.theIndex = findIndexNode(d.indexFile)
if (d.theIndex == nil) or (d.theIndex.kind != rnDefList):
rawMessage(errXisNoValidIndexFile, gIndexFile)
clearIndex(d.theIndex, d.indexValFilename)
else:
d.indexFile = newRstNode(rnInner)
h = newRstNode(rnOverline)
h.level = 1
addSon(h, newRstNode(rnLeaf, "Index"))
addSon(d.indexFile, h)
h = newRstNode(rnIndex)
addSon(h, nil) # no argument
addSon(h, nil) # no options
d.theIndex = newRstNode(rnDefList)
addSon(h, d.theIndex)
addSon(d.indexFile, h)
proc newDocumentor(filename: string): PDoc =
new(result)
result.tocPart = @[]
result.filename = filename
result.id = 100
result.splitAfter = 20
var s = getConfigVar("split.item.toc")
if s != "": result.splitAfter = parseInt(s)
proc getVarIdx(varnames: openarray[string], id: string): int =
for i in countup(0, high(varnames)):
if cmpIgnoreStyle(varnames[i], id) == 0:
return i
result = -1
proc ropeFormatNamedVars(frmt: TFormatStr, varnames: openarray[string],
varvalues: openarray[PRope]): PRope =
var i = 0
var L = len(frmt)
result = nil
var num = 0
while i < L:
if frmt[i] == '$':
inc(i) # skip '$'
case frmt[i]
of '#':
app(result, varvalues[num])
inc(num)
inc(i)
of '$':
app(result, "$")
inc(i)
of '0'..'9':
var j = 0
while true:
j = (j * 10) + Ord(frmt[i]) - ord('0')
inc(i)
if (i > L + 0 - 1) or not (frmt[i] in {'0'..'9'}): break
if j > high(varvalues) + 1: internalError("ropeFormatNamedVars")
num = j
app(result, varvalues[j - 1])
of 'A'..'Z', 'a'..'z', '\x80'..'\xFF':
var id = ""
while true:
add(id, frmt[i])
inc(i)
if not (frmt[i] in {'A'..'Z', '_', 'a'..'z', '\x80'..'\xFF'}): break
var idx = getVarIdx(varnames, id)
if idx >= 0: app(result, varvalues[idx])
else: rawMessage(errUnkownSubstitionVar, id)
of '{':
var id = ""
inc(i)
while frmt[i] != '}':
if frmt[i] == '\0': rawMessage(errTokenExpected, "}")
add(id, frmt[i])
inc(i)
inc(i) # skip }
# search for the variable:
var idx = getVarIdx(varnames, id)
if idx >= 0: app(result, varvalues[idx])
else: rawMessage(errUnkownSubstitionVar, id)
else: InternalError("ropeFormatNamedVars")
var start = i
while i < L:
if (frmt[i] != '$'): inc(i)
else: break
if i - 1 >= start: app(result, substr(frmt, start, i - 1))
proc addXmlChar(dest: var string, c: Char) =
case c
of '&': add(dest, "&")
of '<': add(dest, "<")
of '>': add(dest, ">")
of '\"': add(dest, """)
else: add(dest, c)
proc addRtfChar(dest: var string, c: Char) =
case c
of '{': add(dest, "\\{")
of '}': add(dest, "\\}")
of '\\': add(dest, "\\\\")
else: add(dest, c)
proc addTexChar(dest: var string, c: Char) =
case c
of '_': add(dest, "\\_")
of '{': add(dest, "\\symbol{123}")
of '}': add(dest, "\\symbol{125}")
of '[': add(dest, "\\symbol{91}")
of ']': add(dest, "\\symbol{93}")
of '\\': add(dest, "\\symbol{92}")
of '$': add(dest, "\\$")
of '&': add(dest, "\\&")
of '#': add(dest, "\\#")
of '%': add(dest, "\\%")
of '~': add(dest, "\\symbol{126}")
of '@': add(dest, "\\symbol{64}")
of '^': add(dest, "\\symbol{94}")
of '`': add(dest, "\\symbol{96}")
else: add(dest, c)
proc escChar(dest: var string, c: Char) =
if gCmd != cmdRst2Tex: addXmlChar(dest, c)
else: addTexChar(dest, c)
proc nextSplitPoint(s: string, start: int): int =
result = start
while result < len(s) + 0:
case s[result]
of '_': return
of 'a'..'z':
if result + 1 < len(s) + 0:
if s[result + 1] in {'A'..'Z'}: return
else: nil
inc(result)
dec(result) # last valid index
proc esc(s: string, splitAfter: int = - 1): string =
result = ""
if splitAfter >= 0:
var partLen = 0
var j = 0
while j < len(s):
var k = nextSplitPoint(s, j)
if (splitter != " ") or (partLen + k - j + 1 > splitAfter):
partLen = 0
add(result, splitter)
for i in countup(j, k): escChar(result, s[i])
inc(partLen, k - j + 1)
j = k + 1
else:
for i in countup(0, len(s) + 0 - 1): escChar(result, s[i])
proc disp(xml, tex: string): string =
if gCmd != cmdRst2Tex: result = xml
else: result = tex
proc dispF(xml, tex: string, args: openarray[PRope]): PRope =
if gCmd != cmdRst2Tex: result = ropef(xml, args)
else: result = ropef(tex, args)
proc dispA(dest: var PRope, xml, tex: string, args: openarray[PRope]) =
if gCmd != cmdRst2Tex: appf(dest, xml, args)
else: appf(dest, tex, args)
proc renderRstToOut(d: PDoc, n: PRstNode): PRope
proc renderAux(d: PDoc, n: PRstNode, outer: string = "$1"): PRope =
result = nil
for i in countup(0, rsonsLen(n) - 1): app(result, renderRstToOut(d, n.sons[i]))
result = ropef(outer, [result])
proc setIndexForSourceTerm(d: PDoc, name: PRstNode, id: int) =
if d.theIndex == nil: return
var h = newRstNode(rnHyperlink)
var a = newRstNode(rnLeaf, d.indexValFilename & disp("#", "") & $id)
addSon(h, a)
addSon(h, a)
a = newRstNode(rnIdx)
addSon(a, name)
setIndexPair(d.theIndex, a, h)
proc renderIndexTerm(d: PDoc, n: PRstNode): PRope =
inc(d.id)
result = dispF("<span id=\"$1\">$2</span>", "$2\\label{$1}",
[toRope(d.id), renderAux(d, n)])
var h = newRstNode(rnHyperlink)
var a = newRstNode(rnLeaf, d.indexValFilename & disp("#", "") & $d.id)
addSon(h, a)
addSon(h, a)
setIndexPair(d.theIndex, n, h)
proc genComment(d: PDoc, n: PNode): PRope =
var dummyHasToc: bool
if n.comment != nil and startsWith(n.comment, "##"):
result = renderRstToOut(d, rstParse(n.comment, true, toFilename(n.info),
toLineNumber(n.info), toColumn(n.info),
dummyHasToc))
proc genRecComment(d: PDoc, n: PNode): PRope =
if n == nil: return nil
result = genComment(d, n)
if result == nil:
if not (n.kind in {nkEmpty..nkNilLit}):
for i in countup(0, sonsLen(n) - 1):
result = genRecComment(d, n.sons[i])
if result != nil: return
else:
n.comment = nil
proc isVisible(n: PNode): bool =
result = false
if n.kind == nkPostfix:
if (sonsLen(n) == 2) and (n.sons[0].kind == nkIdent):
var v = n.sons[0].ident
result = (v.id == ord(wStar)) or (v.id == ord(wMinus))
elif n.kind == nkSym:
result = sfExported in n.sym.flags
elif n.kind == nkPragmaExpr:
result = isVisible(n.sons[0])
proc getName(n: PNode, splitAfter: int = - 1): string =
case n.kind
of nkPostfix: result = getName(n.sons[1], splitAfter)
of nkPragmaExpr: result = getName(n.sons[0], splitAfter)
of nkSym: result = esc(n.sym.name.s, splitAfter)
of nkIdent: result = esc(n.ident.s, splitAfter)
of nkAccQuoted:
result = esc("`")
for i in 0.. <n.len: result.add(getName(n[i], splitAfter))
result.add esc("`")
else:
internalError(n.info, "getName()")
result = ""
proc getRstName(n: PNode): PRstNode =
case n.kind
of nkPostfix: result = getRstName(n.sons[1])
of nkPragmaExpr: result = getRstName(n.sons[0])
of nkSym: result = newRstNode(rnLeaf, n.sym.name.s)
of nkIdent: result = newRstNode(rnLeaf, n.ident.s)
of nkAccQuoted:
result = getRstName(n.sons[0])
for i in 1 .. <n.len: result.text.add(getRstName(n[i]).text)
else:
internalError(n.info, "getRstName()")
result = nil
proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) =
if not isVisible(nameNode): return
var name = toRope(getName(nameNode))
var result: PRope = nil
var literal = ""
var kind = tkEof
var comm = genRecComment(d, n) # call this here for the side-effect!
var r: TSrcGen
initTokRender(r, n, {renderNoPragmas, renderNoBody, renderNoComments,
renderDocComments})
while true:
getNextTok(r, kind, literal)
case kind
of tkEof:
break
of tkComment:
dispA(result, "<span class=\"Comment\">$1</span>", "\\spanComment{$1}",
[toRope(esc(literal))])
of tokKeywordLow..tokKeywordHigh:
dispA(result, "<span class=\"Keyword\">$1</span>", "\\spanKeyword{$1}",
[toRope(literal)])
of tkOpr:
dispA(result, "<span class=\"Operator\">$1</span>", "\\spanOperator{$1}",
[toRope(esc(literal))])
of tkStrLit..tkTripleStrLit:
dispA(result, "<span class=\"StringLit\">$1</span>",
"\\spanStringLit{$1}", [toRope(esc(literal))])
of tkCharLit:
dispA(result, "<span class=\"CharLit\">$1</span>", "\\spanCharLit{$1}",
[toRope(esc(literal))])
of tkIntLit..tkInt64Lit:
dispA(result, "<span class=\"DecNumber\">$1</span>",
"\\spanDecNumber{$1}", [toRope(esc(literal))])
of tkFloatLit..tkFloat64Lit:
dispA(result, "<span class=\"FloatNumber\">$1</span>",
"\\spanFloatNumber{$1}", [toRope(esc(literal))])
of tkSymbol:
dispA(result, "<span class=\"Identifier\">$1</span>",
"\\spanIdentifier{$1}", [toRope(esc(literal))])
of tkInd, tkSad, tkDed, tkSpaces:
app(result, literal)
of tkParLe, tkParRi, tkBracketLe, tkBracketRi, tkCurlyLe, tkCurlyRi,
tkBracketDotLe, tkBracketDotRi, tkCurlyDotLe, tkCurlyDotRi, tkParDotLe,
tkParDotRi, tkComma, tkSemiColon, tkColon, tkEquals, tkDot, tkDotDot,
tkAccent:
dispA(result, "<span class=\"Other\">$1</span>", "\\spanOther{$1}",
[toRope(esc(literal))])
else: InternalError(n.info, "docgen.genThing(" & toktypeToStr[kind] & ')')
inc(d.id)
app(d.section[k], ropeFormatNamedVars(getConfigVar("doc.item"),
["name", "header", "desc", "itemID"],
[name, result, comm, toRope(d.id)]))
app(d.toc[k], ropeFormatNamedVars(getConfigVar("doc.item.toc"),
["name", "header", "desc", "itemID"], [
toRope(getName(nameNode, d.splitAfter)), result, comm, toRope(d.id)]))
setIndexForSourceTerm(d, getRstName(nameNode), d.id)
proc renderHeadline(d: PDoc, n: PRstNode): PRope =
result = nil
for i in countup(0, rsonsLen(n) - 1): app(result, renderRstToOut(d, n.sons[i]))
var refname = toRope(rstnodeToRefname(n))
if d.hasToc:
var length = len(d.tocPart)
setlen(d.tocPart, length + 1)
d.tocPart[length].refname = refname
d.tocPart[length].n = n
d.tocPart[length].header = result
result = dispF(
"<h$1><a class=\"toc-backref\" id=\"$2\" href=\"#$2_toc\">$3</a></h$1>",
"\\rsth$4{$3}\\label{$2}$n", [toRope(n.level),
d.tocPart[length].refname, result,
toRope(chr(n.level - 1 + ord('A')) & "")])
else:
result = dispF("<h$1 id=\"$2\">$3</h$1>", "\\rsth$4{$3}\\label{$2}$n", [
toRope(n.level), refname, result,
toRope(chr(n.level - 1 + ord('A')) & "")])
proc renderOverline(d: PDoc, n: PRstNode): PRope =
var t: PRope = nil
for i in countup(0, rsonsLen(n) - 1): app(t, renderRstToOut(d, n.sons[i]))
result = nil
if d.meta[metaTitle] == nil:
d.meta[metaTitle] = t
elif d.meta[metaSubtitle] == nil:
d.meta[metaSubtitle] = t
else:
result = dispF("<h$1 id=\"$2\"><center>$3</center></h$1>",
"\\rstov$4{$3}\\label{$2}$n", [toRope(n.level),
toRope(rstnodeToRefname(n)), t, toRope($chr(n.level - 1 + ord('A')))])
proc renderRstToRst(d: PDoc, n: PRstNode): PRope
proc renderRstSons(d: PDoc, n: PRstNode): PRope =
for i in countup(0, rsonsLen(n) - 1):
app(result, renderRstToRst(d, n.sons[i]))
proc renderRstToRst(d: PDoc, n: PRstNode): PRope =
# this is needed for the index generation; it may also be useful for
# debugging, but most code is already debugged...
const
lvlToChar: array[0..8, char] = ['!', '=', '-', '~', '`', '<', '*', '|', '+']
result = nil
if n == nil: return
var ind = toRope(repeatChar(d.indent))
case n.kind
of rnInner:
result = renderRstSons(d, n)
of rnHeadline:
result = renderRstSons(d, n)
var L = ropeLen(result)
result = ropef("$n$1$2$n$1$3",
[ind, result, toRope(repeatChar(L, lvlToChar[n.level]))])
of rnOverline:
result = renderRstSons(d, n)
var L = ropeLen(result)
result = ropef("$n$1$3$n$1$2$n$1$3",
[ind, result, toRope(repeatChar(L, lvlToChar[n.level]))])
of rnTransition:
result = ropef("$n$n$1$2$n$n", [ind, toRope(repeatChar(78-d.indent, '-'))])
of rnParagraph:
result = renderRstSons(d, n)
result = ropef("$n$n$1$2", [ind, result])
of rnBulletItem:
inc(d.indent, 2)
result = renderRstSons(d, n)
if result != nil: result = ropef("$n$1* $2", [ind, result])
dec(d.indent, 2)
of rnEnumItem:
inc(d.indent, 4)
result = renderRstSons(d, n)
if result != nil: result = ropef("$n$1(#) $2", [ind, result])
dec(d.indent, 4)
of rnOptionList, rnFieldList, rnDefList, rnDefItem, rnLineBlock, rnFieldName,
rnFieldBody, rnStandaloneHyperlink, rnBulletList, rnEnumList:
result = renderRstSons(d, n)
of rnDefName:
result = renderRstSons(d, n)
result = ropef("$n$n$1$2", [ind, result])
of rnDefBody:
inc(d.indent, 2)
result = renderRstSons(d, n)
if n.sons[0].kind != rnBulletList: result = ropef("$n$1 $2", [ind, result])
dec(d.indent, 2)
of rnField:
result = renderRstToRst(d, n.sons[0])
var L = max(ropeLen(result) + 3, 30)
inc(d.indent, L)
result = ropef("$n$1:$2:$3$4", [ind, result, toRope(
repeatChar(L - ropeLen(result) - 2)), renderRstToRst(d, n.sons[1])])
dec(d.indent, L)
of rnLineBlockItem:
result = renderRstSons(d, n)
result = ropef("$n$1| $2", [ind, result])
of rnBlockQuote:
inc(d.indent, 2)
result = renderRstSons(d, n)
dec(d.indent, 2)
of rnRef:
result = renderRstSons(d, n)
result = ropef("`$1`_", [result])
of rnHyperlink:
result = ropef("`$1 <$2>`_",
[renderRstToRst(d, n.sons[0]), renderRstToRst(d, n.sons[1])])
of rnGeneralRole:
result = renderRstToRst(d, n.sons[0])
result = ropef("`$1`:$2:", [result, renderRstToRst(d, n.sons[1])])
of rnSub:
result = renderRstSons(d, n)
result = ropef("`$1`:sub:", [result])
of rnSup:
result = renderRstSons(d, n)
result = ropef("`$1`:sup:", [result])
of rnIdx:
result = renderRstSons(d, n)
result = ropef("`$1`:idx:", [result])
of rnEmphasis:
result = renderRstSons(d, n)
result = ropef("*$1*", [result])
of rnStrongEmphasis:
result = renderRstSons(d, n)
result = ropef("**$1**", [result])
of rnInterpretedText:
result = renderRstSons(d, n)
result = ropef("`$1`", [result])
of rnInlineLiteral:
inc(d.verbatim)
result = renderRstSons(d, n)
result = ropef("``$1``", [result])
dec(d.verbatim)
of rnLeaf:
if (d.verbatim == 0) and (n.text == "\\"):
result = toRope("\\\\") # XXX: escape more special characters!
else:
result = toRope(n.text)
of rnIndex:
inc(d.indent, 3)
if n.sons[2] != nil: result = renderRstSons(d, n.sons[2])
dec(d.indent, 3)
result = ropef("$n$n$1.. index::$n$2", [ind, result])
of rnContents:
result = ropef("$n$n$1.. contents::", [ind])
else: rawMessage(errCannotRenderX, $n.kind)
proc renderTocEntry(d: PDoc, e: TTocEntry): PRope =
result = dispF(
"<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): PRope =
result = nil
while j <= high(d.tocPart):
var a = abs(d.tocPart[j].n.level)
if (a == lvl):
app(result, renderTocEntry(d, d.tocPart[j]))
inc(j)
elif (a > lvl):
app(result, renderTocEntries(d, j, a))
else:
break
if lvl > 1:
result = dispF("<ul class=\"simple\">$1</ul>",
"\\begin{enumerate}$1\\end{enumerate}", [result])
proc fieldAux(s: string): PRope =
result = toRope(strip(s))
proc renderImage(d: PDoc, n: PRstNode): PRope =
var options: PRope = nil
var s = getFieldValue(n, "scale")
if s != "": dispA(options, " scale=\"$1\"", " scale=$1", [fieldAux(s)])
s = getFieldValue(n, "height")
if s != "": dispA(options, " height=\"$1\"", " height=$1", [fieldAux(s)])
s = getFieldValue(n, "width")
if s != "": dispA(options, " width=\"$1\"", " width=$1", [fieldAux(s)])
s = getFieldValue(n, "alt")
if s != "": dispA(options, " alt=\"$1\"", "", [fieldAux(s)])
s = getFieldValue(n, "align")
if s != "": dispA(options, " align=\"$1\"", "", [fieldAux(s)])
if options != nil: options = dispF("$1", "[$1]", [options])
result = dispF("<img src=\"$1\"$2 />", "\\includegraphics$2{$1}",
[toRope(getArgument(n)), options])
if rsonsLen(n) >= 3: app(result, renderRstToOut(d, n.sons[2]))
proc renderCodeBlock(d: PDoc, n: PRstNode): PRope =
result = nil
if n.sons[2] == nil: return
var m = n.sons[2].sons[0]
if (m.kind != rnLeaf): InternalError("renderCodeBlock")
var langstr = strip(getArgument(n))
var lang: TSourceLanguage
if langstr == "":
lang = langNimrod # default language
else:
lang = getSourceLanguage(langstr)
if lang == langNone:
rawMessage(warnLanguageXNotSupported, langstr)
result = toRope(m.text)
else:
var g: TGeneralTokenizer
initGeneralTokenizer(g, m.text)
while true:
getNextToken(g, lang)
case g.kind
of gtEof: break
of gtNone, gtWhitespace:
app(result, substr(m.text, g.start + 0, g.length + g.start - 1))
else:
dispA(result, "<span class=\"$2\">$1</span>", "\\span$2{$1}", [
toRope(esc(substr(m.text, g.start + 0, g.length + g.start - 1))),
toRope(tokenClassToStr[g.kind])])
deinitGeneralTokenizer(g)
if result != nil:
result = dispF("<pre>$1</pre>", "\\begin{rstpre}$n$1$n\\end{rstpre}$n",
[result])
proc renderContainer(d: PDoc, n: PRstNode): PRope =
result = renderRstToOut(d, n.sons[2])
var arg = toRope(strip(getArgument(n)))
if arg == nil: result = dispF("<div>$1</div>", "$1", [result])
else: result = dispF("<div class=\"$1\">$2</div>", "$2", [arg, result])
proc texColumns(n: PRstNode): string =
result = ""
for i in countup(1, rsonsLen(n)): add(result, "|X")
proc renderField(d: PDoc, n: PRstNode): PRope =
var b = false
if gCmd == cmdRst2Tex:
var fieldname = addNodes(n.sons[0])
var fieldval = toRope(esc(strip(addNodes(n.sons[1]))))
if cmpIgnoreStyle(fieldname, "author") == 0:
if d.meta[metaAuthor] == nil:
d.meta[metaAuthor] = fieldval
b = true
elif cmpIgnoreStyle(fieldName, "version") == 0:
if d.meta[metaVersion] == nil:
d.meta[metaVersion] = fieldval
b = true
if b: result = nil
else: result = renderAux(d, n, disp("<tr>$1</tr>$n", "$1"))
proc renderRstToOut(d: PDoc, n: PRstNode): PRope =
if n == nil:
return nil
case n.kind
of rnInner: result = renderAux(d, n)
of rnHeadline: result = renderHeadline(d, n)
of rnOverline: result = renderOverline(d, n)
of rnTransition: result = renderAux(d, n, disp("<hr />\n", "\\hrule\n"))
of rnParagraph: result = renderAux(d, n, disp("<p>$1</p>\n", "$1$n$n"))
of rnBulletList:
result = renderAux(d, n, disp("<ul class=\"simple\">$1</ul>\n",
"\\begin{itemize}$1\\end{itemize}\n"))
of rnBulletItem, rnEnumItem:
result = renderAux(d, n, disp("<li>$1</li>\n", "\\item $1\n"))
of rnEnumList:
result = renderAux(d, n, disp("<ol class=\"simple\">$1</ol>\n",
"\\begin{enumerate}$1\\end{enumerate}\n"))
of rnDefList:
result = renderAux(d, n, disp("<dl class=\"docutils\">$1</dl>\n",
"\\begin{description}$1\\end{description}\n"))
of rnDefItem: result = renderAux(d, n)
of rnDefName: result = renderAux(d, n, disp("<dt>$1</dt>\n", "\\item[$1] "))
of rnDefBody: result = renderAux(d, n, disp("<dd>$1</dd>\n", "$1\n"))
of rnFieldList:
result = nil
for i in countup(0, rsonsLen(n) - 1):
app(result, renderRstToOut(d, n.sons[i]))
if result != nil:
result = dispf(
"<table class=\"docinfo\" frame=\"void\" rules=\"none\">" &
"<col class=\"docinfo-name\" />" &
"<col class=\"docinfo-content\" />" &
"<tbody valign=\"top\">$1" &
"</tbody></table>",
"\\begin{description}$1\\end{description}\n",
[result])
of rnField: result = renderField(d, n)
of rnFieldName:
result = renderAux(d, n, disp("<th class=\"docinfo-name\">$1:</th>",
"\\item[$1:]"))
of rnFieldBody:
result = renderAux(d, n, disp("<td>$1</td>", " $1$n"))
of rnIndex:
result = renderRstToOut(d, n.sons[2])
of rnOptionList:
result = renderAux(d, n, disp("<table frame=\"void\">$1</table>",
"\\begin{description}$n$1\\end{description}\n"))
of rnOptionListItem:
result = renderAux(d, n, disp("<tr>$1</tr>$n", "$1"))
of rnOptionGroup:
result = renderAux(d, n, disp("<th align=\"left\">$1</th>", "\\item[$1]"))
of rnDescription:
result = renderAux(d, n, disp("<td align=\"left\">$1</td>$n", " $1$n"))
of rnOption, rnOptionString, rnOptionArgument:
InternalError("renderRstToOut")
of rnLiteralBlock:
result = renderAux(d, n, disp("<pre>$1</pre>$n",
"\\begin{rstpre}$n$1$n\\end{rstpre}$n"))
of rnQuotedLiteralBlock:
InternalError("renderRstToOut")
of rnLineBlock:
result = renderAux(d, n, disp("<p>$1</p>", "$1$n$n"))
of rnLineBlockItem:
result = renderAux(d, n, disp("$1<br />", "$1\\\\$n"))
of rnBlockQuote:
result = renderAux(d, n, disp("<blockquote><p>$1</p></blockquote>$n",
"\\begin{quote}$1\\end{quote}$n"))
of rnTable, rnGridTable:
result = renderAux(d, n, disp(
"<table border=\"1\" class=\"docutils\">$1</table>",
"\\begin{table}\\begin{rsttab}{" &
texColumns(n) & "|}$n\\hline$n$1\\end{rsttab}\\end{table}"))
of rnTableRow:
if rsonsLen(n) >= 1:
result = renderRstToOut(d, n.sons[0])
for i in countup(1, rsonsLen(n) - 1):
dispa(result, "$1", " & $1", [renderRstToOut(d, n.sons[i])])
result = dispf("<tr>$1</tr>$n", "$1\\\\$n\\hline$n", [result])
else:
result = nil
of rnTableDataCell: result = renderAux(d, n, disp("<td>$1</td>", "$1"))
of rnTableHeaderCell:
result = renderAux(d, n, disp("<th>$1</th>", "\\textbf{$1}"))
of rnLabel:
InternalError("renderRstToOut") # used for footnotes and other
of rnFootnote:
InternalError("renderRstToOut") # a footnote
of rnCitation:
InternalError("renderRstToOut") # similar to footnote
of rnRef:
result = dispF("<a class=\"reference external\" href=\"#$2\">$1</a>",
"$1\\ref{$2}", [renderAux(d, n), toRope(rstnodeToRefname(n))])
of rnStandaloneHyperlink:
result = renderAux(d, n, disp(
"<a class=\"reference external\" href=\"$1\">$1</a>",
"\\href{$1}{$1}"))
of rnHyperlink:
result = dispF("<a class=\"reference external\" href=\"$2\">$1</a>",
"\\href{$2}{$1}",
[renderRstToOut(d, n.sons[0]), renderRstToOut(d, n.sons[1])])
of rnDirArg, rnRaw: result = renderAux(d, n)
of rnRawHtml:
if gCmd != cmdRst2Tex:
result = toRope(addNodes(lastSon(n)))
of rnRawLatex:
if gCmd == cmdRst2Tex:
result = toRope(addNodes(lastSon(n)))
of rnImage, rnFigure: result = renderImage(d, n)
of rnCodeBlock: result = renderCodeBlock(d, n)
of rnContainer: result = renderContainer(d, n)
of rnSubstitutionReferences, rnSubstitutionDef:
result = renderAux(d, n, disp("|$1|", "|$1|"))
of rnDirective:
result = renderAux(d, n, "") # Inline markup:
of rnGeneralRole:
result = dispF("<span class=\"$2\">$1</span>", "\\span$2{$1}",
[renderRstToOut(d, n.sons[0]), renderRstToOut(d, n.sons[1])])
of rnSub: result = renderAux(d, n, disp("<sub>$1</sub>", "\\rstsub{$1}"))
of rnSup: result = renderAux(d, n, disp("<sup>$1</sup>", "\\rstsup{$1}"))
of rnEmphasis: result = renderAux(d, n, disp("<em>$1</em>", "\\emph{$1}"))
of rnStrongEmphasis:
result = renderAux(d, n, disp("<strong>$1</strong>", "\\textbf{$1}"))
of rnInterpretedText:
result = renderAux(d, n, disp("<cite>$1</cite>", "\\emph{$1}"))
of rnIdx:
if d.theIndex == nil:
result = renderAux(d, n, disp("<span>$1</span>", "\\emph{$1}"))
else:
result = renderIndexTerm(d, n)
of rnInlineLiteral:
result = renderAux(d, n, disp(
"<tt class=\"docutils literal\"><span class=\"pre\">$1</span></tt>",
"\\texttt{$1}"))
of rnLeaf: result = toRope(esc(n.text))
of rnContents: d.hasToc = true
of rnTitle: d.meta[metaTitle] = renderRstToOut(d, n.sons[0])
else: InternalError("renderRstToOut")
proc checkForFalse(n: PNode): bool =
result = n.kind == nkIdent and IdentEq(n.ident, "false")
proc traceDeps(d: PDoc, n: PNode) =
const k = skModule
if d.section[k] != nil: app(d.section[k], ", ")
dispA(d.section[k],
"<a class=\"reference external\" href=\"$1.html\">$1</a>",
"$1", [toRope(getModuleName(n))])
proc generateDoc(d: PDoc, n: PNode) =
case n.kind
of nkCommentStmt: app(d.modDesc, genComment(d, n))
of nkProcDef: genItem(d, n, n.sons[namePos], skProc)
of nkMethodDef: genItem(d, n, n.sons[namePos], skMethod)
of nkIteratorDef: genItem(d, n, n.sons[namePos], skIterator)
of nkMacroDef: genItem(d, n, n.sons[namePos], skMacro)
of nkTemplateDef: genItem(d, n, n.sons[namePos], skTemplate)
of nkConverterDef: genItem(d, n, n.sons[namePos], skConverter)
of nkTypeSection, nkVarSection, nkLetSection, nkConstSection:
for i in countup(0, sonsLen(n) - 1):
if n.sons[i].kind != nkCommentStmt:
# order is always 'type var let const':
genItem(d, n.sons[i], n.sons[i].sons[0],
succ(skType, ord(n.kind)-ord(nkTypeSection)))
of nkStmtList:
for i in countup(0, sonsLen(n) - 1): generateDoc(d, n.sons[i])
of nkWhenStmt:
# generate documentation for the first branch only:
if not checkForFalse(n.sons[0].sons[0]):
generateDoc(d, lastSon(n.sons[0]))
of nkImportStmt:
for i in 0 .. sonsLen(n)-1: traceDeps(d, n.sons[i])
of nkFromStmt: traceDeps(d, n.sons[0])
else: nil
proc genSection(d: PDoc, kind: TSymKind) =
const sectionNames: array[skModule..skTemplate, string] = [
"Imports", "Types", "Vars", "Lets", "Consts", "Vars", "Procs", "Methods",
"Iterators", "Converters", "Macros", "Templates"
]
if d.section[kind] == nil: return
var title = toRope(sectionNames[kind])
d.section[kind] = ropeFormatNamedVars(getConfigVar("doc.section"), [
"sectionid", "sectionTitle", "sectionTitleID", "content"], [
toRope(ord(kind)), title, toRope(ord(kind) + 50), d.section[kind]])
d.toc[kind] = ropeFormatNamedVars(getConfigVar("doc.section.toc"), [
"sectionid", "sectionTitle", "sectionTitleID", "content"], [
toRope(ord(kind)), title, toRope(ord(kind) + 50), d.toc[kind]])
proc genOutFile(d: PDoc): PRope =
var
code, toc, title, content: PRope
bodyname: string
j: int
j = 0
toc = renderTocEntries(d, j, 1)
code = nil
content = nil
title = nil
for i in countup(low(TSymKind), high(TSymKind)):
genSection(d, i)
app(toc, d.toc[i])
if toc != nil:
toc = ropeFormatNamedVars(getConfigVar("doc.toc"), ["content"], [toc])
for i in countup(low(TSymKind), high(TSymKind)): app(code, d.section[i])
if d.meta[metaTitle] != nil: title = d.meta[metaTitle]
else: title = toRope("Module " &
extractFilename(changeFileExt(d.filename, "")))
if d.hasToc: bodyname = "doc.body_toc"
else: bodyname = "doc.body_no_toc"
content = ropeFormatNamedVars(getConfigVar(bodyname), ["title",
"tableofcontents", "moduledesc", "date", "time", "content"],
[title, toc, d.modDesc, toRope(getDateStr()),
toRope(getClockStr()), code])
if optCompileOnly notin gGlobalOptions:
code = ropeFormatNamedVars(getConfigVar("doc.file"), ["title",
"tableofcontents", "moduledesc", "date", "time",
"content", "author", "version"],
[title, toc, d.modDesc, toRope(getDateStr()),
toRope(getClockStr()), content, d.meta[metaAuthor],
d.meta[metaVersion]])
else:
code = content
result = code
proc generateIndex(d: PDoc) =
if d.theIndex != nil:
sortIndex(d.theIndex)
writeRope(renderRstToRst(d, d.indexFile), gIndexFile)
proc writeOutput(d: PDoc, filename, outExt: string) =
var content = genOutFile(d)
if optStdout in gGlobalOptions:
writeRope(stdout, content)
else:
writeRope(content, getOutFile(filename, outExt))
proc CommandDoc =
var ast = parseFile(addFileExt(gProjectFull, nimExt))
if ast == nil: return
var d = newDocumentor(gProjectFull)
initIndexFile(d)
d.hasToc = true
generateDoc(d, ast)
writeOutput(d, gProjectFull, HtmlExt)
generateIndex(d)
proc CommandRstAux(filename, outExt: string) =
var filen = addFileExt(filename, "txt")
var d = newDocumentor(filen)
initIndexFile(d)
var rst = rstParse(readFile(filen), false, filen, 0, 1, d.hasToc)
d.modDesc = renderRstToOut(d, rst)
writeOutput(d, filename, outExt)
generateIndex(d)
proc CommandRst2Html =
CommandRstAux(gProjectFull, HtmlExt)
proc CommandRst2TeX =
splitter = "\\-"
CommandRstAux(gProjectFull, TexExt)
# ---------- forum ---------------------------------------------------------
proc setupConfig*() =
msgs.gErrorMax = 1000_000
setConfigVar("split.item.toc", "20")
setConfigVar("doc.section", """
<div class="section" id="$sectionID">
<h1><a class="toc-backref" href="#$sectionTitleID">$sectionTitle</a></h1>
<dl class="item">
$content
</dl></div>
""")
setConfigVar("doc.section.toc", """
<li>
<a class="reference" href="#$sectionID" id="$sectionTitleID">$sectionTitle</a>
<ul class="simple">
$content
</ul>
</li>
""")
setConfigVar("doc.item", """
<dt id="$itemID"><pre>$header</pre></dt>
<dd>
$desc
</dd>
""")
setConfigVar("doc.item.toc", """
<li><a class="reference" href="#$itemID">$name</a></li>
""")
setConfigVar("doc.toc", """
<div class="navigation" id="navigation">
<ul class="simple">
$content
</ul>
</div>""")
setConfigVar("doc.body_toc", """
$tableofcontents
<div class="content" id="content">
$moduledesc
$content
</div>
""")
setConfigVar("doc.body_no_toc", "$moduledesc $content")
setConfigVar("doc.file", "$content")
proc rstToHtml*(s: string): string =
## exported for *nimforum*.
const filen = "input"
var d = newDocumentor(filen)
var dummyHasToc = false
var rst = rstParse(s, false, filen, 0, 1, dummyHasToc)
d.modDesc = renderRstToOut(d, rst)
let res = genOutFile(d)
result = res.ropeToStr