jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docgen compiles again

Browse source
This commit is contained in:
Andreas Rumpf 2018-05-11 16:06:36 +02:00
commit efc2ce1b7e
2 changed files with 69 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

125
compiler/docgen.nim
View file

@ -29,6 +29,7 @@ type
jArray: JsonNode jArray: JsonNode
types: TStrTable types: TStrTable
isPureRst: bool isPureRst: bool
conf: ConfigRef
PDoc* = ref TDocumentor ## Alias to type less. PDoc* = ref TDocumentor ## Alias to type less.
@ -88,11 +89,12 @@ proc parseRst(text, filename: string,
proc newDocumentor*(filename: string, conf: ConfigRef): PDoc = proc newDocumentor*(filename: string, conf: ConfigRef): PDoc =
declareClosures() declareClosures()
new(result) new(result)
result.conf = conf
initRstGenerator(result[], (if gCmd != cmdRst2tex: outHtml else: outLatex), initRstGenerator(result[], (if gCmd != cmdRst2tex: outHtml else: outLatex),
options.gConfigVars, filename, {roSupportRawDirective}, conf.configVars, filename, {roSupportRawDirective},
docgenFindFile, compilerMsgHandler) docgenFindFile, compilerMsgHandler)
if config.hasKey("doc.googleAnalytics"): if conf.configVars.hasKey("doc.googleAnalytics"):
result.analytics = """ result.analytics = """
<script> <script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
@ -104,7 +106,7 @@ proc newDocumentor*(filename: string, conf: ConfigRef): PDoc =
ga('send', 'pageview'); ga('send', 'pageview');
</script> </script>
""" % [config.getOrDefault"doc.googleAnalytics"] """ % [conf.configVars.getOrDefault"doc.googleAnalytics"]
else: else:
result.analytics = "" result.analytics = ""
@ -125,7 +127,8 @@ proc getVarIdx(varnames: openArray[string], id: string): int =
return i return i
result = -1 result = -1
proc ropeFormatNamedVars(frmt: FormatStr, varnames: openArray[string], proc ropeFormatNamedVars(conf: ConfigRef; frmt: FormatStr,
varnames: openArray[string],
varvalues: openArray[Rope]): Rope = varvalues: openArray[Rope]): Rope =
var i = 0 var i = 0
var L = len(frmt) var L = len(frmt)
@ -148,7 +151,8 @@ proc ropeFormatNamedVars(frmt: FormatStr, varnames: openArray[string],
j = (j * 10) + ord(frmt[i]) - ord('0') j = (j * 10) + ord(frmt[i]) - ord('0')
inc(i) inc(i)
if (i > L + 0 - 1) or not (frmt[i] in {'0'..'9'}): break if (i > L + 0 - 1) or not (frmt[i] in {'0'..'9'}): break
if j > high(varvalues) + 1: internalError("ropeFormatNamedVars") if j > high(varvalues) + 1:
rawMessage(conf, errGenerated, "Invalid format string; too many $s: " & frmt)
num = j num = j
add(result, varvalues[j - 1]) add(result, varvalues[j - 1])
of 'A'..'Z', 'a'..'z', '\x80'..'\xFF': of 'A'..'Z', 'a'..'z', '\x80'..'\xFF':
@ -159,20 +163,23 @@ proc ropeFormatNamedVars(frmt: FormatStr, varnames: openArray[string],
if not (frmt[i] in {'A'..'Z', '_', 'a'..'z', '\x80'..'\xFF'}): break if not (frmt[i] in {'A'..'Z', '_', 'a'..'z', '\x80'..'\xFF'}): break
var idx = getVarIdx(varnames, id) var idx = getVarIdx(varnames, id)
if idx >= 0: add(result, varvalues[idx]) if idx >= 0: add(result, varvalues[idx])
else: rawMessage(errUnknownSubstitionVar, id) else: rawMessage(conf, errGenerated, "unknown substition variable: " & id)
of '{': of '{':
var id = "" var id = ""
inc(i) inc(i)
while frmt[i] != '}': while i < frmt.len and frmt[i] != '}':
if frmt[i] == '\0': rawMessage(errTokenExpected, "}")
add(id, frmt[i]) add(id, frmt[i])
inc(i) inc(i)
if i >= frmt.len:
rawMessage(conf, errGenerated, "expected closing '}'")
else:
inc(i) # skip } inc(i) # skip }
# search for the variable: # search for the variable:
var idx = getVarIdx(varnames, id) let idx = getVarIdx(varnames, id)
if idx >= 0: add(result, varvalues[idx]) if idx >= 0: add(result, varvalues[idx])
else: rawMessage(errUnknownSubstitionVar, id) else: rawMessage(conf, errGenerated, "unknown substition variable: " & id)
else: internalError("ropeFormatNamedVars") else:
add(result, "$")
var start = i var start = i
while i < L: while i < L:
if frmt[i] != '$': inc(i) if frmt[i] != '$': inc(i)
@ -185,7 +192,7 @@ proc genComment(d: PDoc, n: PNode): string =
if n.comment != nil: if n.comment != nil:
renderRstToOut(d[], parseRst(n.comment, toFilename(n.info), renderRstToOut(d[], parseRst(n.comment, toFilename(n.info),
toLinenumber(n.info), toColumn(n.info), toLinenumber(n.info), toColumn(n.info),
dummyHasToc, d.options), result) dummyHasToc, d.options, d.conf), result)
proc genRecComment(d: PDoc, n: PNode): Rope = proc genRecComment(d: PDoc, n: PNode): Rope =
if n == nil: return nil if n == nil: return nil
@ -340,7 +347,6 @@ proc getName(d: PDoc, n: PNode, splitAfter = -1): string =
of nkOpenSymChoice, nkClosedSymChoice: of nkOpenSymChoice, nkClosedSymChoice:
result = getName(d, n[0], splitAfter) result = getName(d, n[0], splitAfter)
else: else:
internalError(n.info, "getName()")
result = "" result = ""
proc getNameIdent(n: PNode): PIdent = proc getNameIdent(n: PNode): PIdent =
@ -370,7 +376,6 @@ proc getRstName(n: PNode): PRstNode =
of nkOpenSymChoice, nkClosedSymChoice: of nkOpenSymChoice, nkClosedSymChoice:
result = getRstName(n[0]) result = getRstName(n[0])
else: else:
internalError(n.info, "getRstName()")
result = nil result = nil
proc newUniquePlainSymbol(d: PDoc, original: string): string = proc newUniquePlainSymbol(d: PDoc, original: string): string =
@ -494,22 +499,22 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) =
symbolOrIdEncRope = encodeUrl(symbolOrId).rope symbolOrIdEncRope = encodeUrl(symbolOrId).rope
var seeSrcRope: Rope = nil var seeSrcRope: Rope = nil
let docItemSeeSrc = getConfigVar("doc.item.seesrc") let docItemSeeSrc = getConfigVar(d.conf, "doc.item.seesrc")
if docItemSeeSrc.len > 0: if docItemSeeSrc.len > 0:
let cwd = getCurrentDir().canonicalizePath() let cwd = canonicalizePath(d.conf, getCurrentDir())
var path = n.info.toFullPath var path = n.info.toFullPath
if path.startsWith(cwd): if path.startsWith(cwd):
path = path[cwd.len+1 .. ^1].replace('\\', '/') path = path[cwd.len+1 .. ^1].replace('\\', '/')
let gitUrl = getConfigVar("git.url") let gitUrl = getConfigVar(d.conf, "git.url")
if gitUrl.len > 0: if gitUrl.len > 0:
var commit = getConfigVar("git.commit") var commit = getConfigVar(d.conf, "git.commit")
if commit.len == 0: commit = "master" if commit.len == 0: commit = "master"
dispA(seeSrcRope, "$1", "", [ropeFormatNamedVars(docItemSeeSrc, dispA(seeSrcRope, "$1", "", [ropeFormatNamedVars(d.conf, docItemSeeSrc,
["path", "line", "url", "commit"], [rope path, ["path", "line", "url", "commit"], [rope path,
rope($n.info.line), rope gitUrl, rope($n.info.line), rope gitUrl,
rope commit])]) rope commit])])
add(d.section[k], ropeFormatNamedVars(getConfigVar("doc.item"), add(d.section[k], ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.item"),
["name", "header", "desc", "itemID", "header_plain", "itemSym", ["name", "header", "desc", "itemID", "header_plain", "itemSym",
"itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "seeSrc"], "itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "seeSrc"],
[nameRope, result, comm, itemIDRope, plainNameRope, plainSymbolRope, [nameRope, result, comm, itemIDRope, plainNameRope, plainSymbolRope,
@ -520,7 +525,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) =
let att = attachToType(d, nameNode.sym) let att = attachToType(d, nameNode.sym)
if att != nil: if att != nil:
attype = rope esc(d.target, att.name.s) attype = rope esc(d.target, att.name.s)
add(d.toc[k], ropeFormatNamedVars(getConfigVar("doc.item.toc"), add(d.toc[k], ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.item.toc"),
["name", "header", "desc", "itemID", "header_plain", "itemSym", ["name", "header", "desc", "itemID", "header_plain", "itemSym",
"itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "attype"], "itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "attype"],
[rope(getName(d, nameNode, d.splitAfter)), result, comm, [rope(getName(d, nameNode, d.splitAfter)), result, comm,
@ -575,7 +580,7 @@ proc traceDeps(d: PDoc, it: PNode) =
if d.section[k] != nil: add(d.section[k], ", ") if d.section[k] != nil: add(d.section[k], ", ")
dispA(d.section[k], dispA(d.section[k],
"<a class=\"reference external\" href=\"$1.html\">$1</a>", "<a class=\"reference external\" href=\"$1.html\">$1</a>",
"$1", [rope(getModuleName(it))]) "$1", [rope(getModuleName(d.conf, it))])
proc generateDoc*(d: PDoc, n: PNode) = proc generateDoc*(d: PDoc, n: PNode) =
case n.kind case n.kind
@ -708,10 +713,10 @@ proc genSection(d: PDoc, kind: TSymKind) =
] ]
if d.section[kind] == nil: return if d.section[kind] == nil: return
var title = sectionNames[kind].rope var title = sectionNames[kind].rope
d.section[kind] = ropeFormatNamedVars(getConfigVar("doc.section"), [ d.section[kind] = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.section"), [
"sectionid", "sectionTitle", "sectionTitleID", "content"], [ "sectionid", "sectionTitle", "sectionTitleID", "content"], [
ord(kind).rope, title, rope(ord(kind) + 50), d.section[kind]]) ord(kind).rope, title, rope(ord(kind) + 50), d.section[kind]])
d.toc[kind] = ropeFormatNamedVars(getConfigVar("doc.section.toc"), [ d.toc[kind] = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.section.toc"), [
"sectionid", "sectionTitle", "sectionTitleID", "content"], [ "sectionid", "sectionTitle", "sectionTitleID", "content"], [
ord(kind).rope, title, rope(ord(kind) + 50), d.toc[kind]]) ord(kind).rope, title, rope(ord(kind) + 50), d.toc[kind]])
@ -727,7 +732,7 @@ proc genOutFile(d: PDoc): Rope =
genSection(d, i) genSection(d, i)
add(toc, d.toc[i]) add(toc, d.toc[i])
if toc != nil: if toc != nil:
toc = ropeFormatNamedVars(getConfigVar("doc.toc"), ["content"], [toc]) toc = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.toc"), ["content"], [toc])
for i in countup(low(TSymKind), high(TSymKind)): add(code, d.section[i]) for i in countup(low(TSymKind), high(TSymKind)): add(code, d.section[i])
# Extract the title. Non API modules generate an entry in the index table. # Extract the title. Non API modules generate an entry in the index table.
@ -741,13 +746,13 @@ proc genOutFile(d: PDoc): Rope =
let bodyname = if d.hasToc and not d.isPureRst: "doc.body_toc_group" let bodyname = if d.hasToc and not d.isPureRst: "doc.body_toc_group"
elif d.hasToc: "doc.body_toc" elif d.hasToc: "doc.body_toc"
else: "doc.body_no_toc" else: "doc.body_no_toc"
content = ropeFormatNamedVars(getConfigVar(bodyname), ["title", content = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, bodyname), ["title",
"tableofcontents", "moduledesc", "date", "time", "content"], "tableofcontents", "moduledesc", "date", "time", "content"],
[title.rope, toc, d.modDesc, rope(getDateStr()), [title.rope, toc, d.modDesc, rope(getDateStr()),
rope(getClockStr()), code]) rope(getClockStr()), code])
if optCompileOnly notin gGlobalOptions: if optCompileOnly notin gGlobalOptions:
# XXX what is this hack doing here? 'optCompileOnly' means raw output!? # XXX what is this hack doing here? 'optCompileOnly' means raw output!?
code = ropeFormatNamedVars(getConfigVar("doc.file"), ["title", code = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.file"), ["title",
"tableofcontents", "moduledesc", "date", "time", "tableofcontents", "moduledesc", "date", "time",
"content", "author", "version", "analytics"], "content", "author", "version", "analytics"],
[title.rope, toc, d.modDesc, rope(getDateStr()), [title.rope, toc, d.modDesc, rope(getDateStr()),
@ -759,59 +764,59 @@ proc genOutFile(d: PDoc): Rope =
proc generateIndex*(d: PDoc) = proc generateIndex*(d: PDoc) =
if optGenIndex in gGlobalOptions: if optGenIndex in gGlobalOptions:
writeIndexFile(d[], splitFile(options.outFile).dir / writeIndexFile(d[], splitFile(d.conf.outFile).dir /
splitFile(d.filename).name & IndexExt) splitFile(d.filename).name & IndexExt)
proc getOutFile2(filename, ext, dir: string): string = proc getOutFile2(conf: ConfigRef; filename, ext, dir: string): string =
if gWholeProject: if gWholeProject:
let d = if options.outFile != "": options.outFile else: dir let d = if conf.outFile != "": conf.outFile else: dir
createDir(d) createDir(d)
result = d / changeFileExt(filename, ext) result = d / changeFileExt(filename, ext)
else: else:
result = getOutFile(filename, ext) result = getOutFile(conf, filename, ext)
proc writeOutput*(d: PDoc, filename, outExt: string, useWarning = false) = proc writeOutput*(d: PDoc, filename, outExt: string, useWarning = false) =
var content = genOutFile(d) var content = genOutFile(d)
if optStdout in gGlobalOptions: if optStdout in gGlobalOptions:
writeRope(stdout, content) writeRope(stdout, content)
else: else:
writeRope(content, getOutFile2(filename, outExt, "htmldocs"), useWarning) writeRope(content, getOutFile2(d.conf, filename, outExt, "htmldocs"), useWarning)
proc writeOutputJson*(d: PDoc, filename, outExt: string, proc writeOutputJson*(d: PDoc, filename, outExt: string,
useWarning = false) = useWarning = false) =
let content = %*{"orig": d.filename, let content = %*{"orig": d.filename,
"nimble": getPackageName(d.filename), "nimble": getPackageName(d.conf, d.filename),
"entries": d.jArray} "entries": d.jArray}
if optStdout in gGlobalOptions: if optStdout in gGlobalOptions:
write(stdout, $content) write(stdout, $content)
else: else:
var f: File var f: File
if open(f, getOutFile2(splitFile(filename).name, if open(f, getOutFile2(d.conf, splitFile(filename).name,
outExt, "jsondocs"), fmWrite): outExt, "jsondocs"), fmWrite):
write(f, $content) write(f, $content)
close(f) close(f)
else: else:
discard "fixme: error report" discard "fixme: error report"
proc commandDoc*() = proc commandDoc*(conf: ConfigRef) =
var ast = parseFile(gProjectMainIdx.FileIndex, newIdentCache(), newConfigRef()) var ast = parseFile(conf.projectMainIdx.FileIndex, newIdentCache(), conf)
if ast == nil: return if ast == nil: return
var d = newDocumentor(gProjectFull, options.gConfigVars) var d = newDocumentor(conf.projectFull, conf)
d.hasToc = true d.hasToc = true
generateDoc(d, ast) generateDoc(d, ast)
writeOutput(d, gProjectFull, HtmlExt) writeOutput(d, conf.projectFull, HtmlExt)
generateIndex(d) generateIndex(d)
proc commandRstAux(filename, outExt: string) = proc commandRstAux(conf: ConfigRef; filename, outExt: string) =
var filen = addFileExt(filename, "txt") var filen = addFileExt(filename, "txt")
var d = newDocumentor(filen, options.gConfigVars) var d = newDocumentor(filen, conf)
d.onTestSnippet = proc (d: var RstGenerator; filename, cmd: string; d.onTestSnippet = proc (d: var RstGenerator; filename, cmd: string;
status: int; content: string) = status: int; content: string) =
var outp: string var outp: string
if filename.len == 0: if filename.len == 0:
inc(d.id) inc(d.id)
let nameOnly = splitFile(d.filename).name let nameOnly = splitFile(d.filename).name
let subdir = getNimcacheDir() / nameOnly let subdir = getNimcacheDir(conf) / nameOnly
createDir(subdir) createDir(subdir)
outp = subdir / (nameOnly & "_snippet_" & $d.id & ".nim") outp = subdir / (nameOnly & "_snippet_" & $d.id & ".nim")
elif isAbsolute(filename): elif isAbsolute(filename):
@ -821,13 +826,13 @@ proc commandRstAux(filename, outExt: string) =
outp = splitFile(d.filename).dir / filename outp = splitFile(d.filename).dir / filename
writeFile(outp, content) writeFile(outp, content)
let cmd = cmd % quoteShell(outp) let cmd = cmd % quoteShell(outp)
rawMessage(hintExecuting, cmd) rawMessage(conf, hintExecuting, cmd)
if execShellCmd(cmd) != status: if execShellCmd(cmd) != status:
rawMessage(errExecutionOfProgramFailed, cmd) rawMessage(conf, errGenerated, "executing of external program failed: " & cmd)
d.isPureRst = true d.isPureRst = true
var rst = parseRst(readFile(filen), filen, 0, 1, d.hasToc, var rst = parseRst(readFile(filen), filen, 0, 1, d.hasToc,
{roSupportRawDirective}) {roSupportRawDirective}, conf)
var modDesc = newStringOfCap(30_000) var modDesc = newStringOfCap(30_000)
#d.modDesc = newMutableRope(30_000) #d.modDesc = newMutableRope(30_000)
renderRstToOut(d[], rst, modDesc) renderRstToOut(d[], rst, modDesc)
@ -836,17 +841,17 @@ proc commandRstAux(filename, outExt: string) =
writeOutput(d, filename, outExt) writeOutput(d, filename, outExt)
generateIndex(d) generateIndex(d)
proc commandRst2Html*() = proc commandRst2Html*(conf: ConfigRef) =
commandRstAux(gProjectFull, HtmlExt) commandRstAux(conf, conf.projectFull, HtmlExt)
proc commandRst2TeX*() = proc commandRst2TeX*(conf: ConfigRef) =
splitter = "\\-" splitter = "\\-"
commandRstAux(gProjectFull, TexExt) commandRstAux(conf, conf.projectFull, TexExt)
proc commandJson*() = proc commandJson*(conf: ConfigRef) =
var ast = parseFile(gProjectMainIdx.FileIndex, newIdentCache(), newConfigRef()) var ast = parseFile(conf.projectMainIdx.FileIndex, newIdentCache(), conf)
if ast == nil: return if ast == nil: return
var d = newDocumentor(gProjectFull, options.gConfigVars) var d = newDocumentor(conf.projectFull, conf)
d.hasToc = true d.hasToc = true
generateJson(d, ast) generateJson(d, ast)
let json = d.jArray let json = d.jArray
@ -856,12 +861,12 @@ proc commandJson*() =
writeRope(stdout, content) writeRope(stdout, content)
else: else:
#echo getOutFile(gProjectFull, JsonExt) #echo getOutFile(gProjectFull, JsonExt)
writeRope(content, getOutFile(gProjectFull, JsonExt), useWarning = false) writeRope(content, getOutFile(conf, conf.projectFull, JsonExt), useWarning = false)
proc commandTags*() = proc commandTags*(conf: ConfigRef) =
var ast = parseFile(gProjectMainIdx.FileIndex, newIdentCache(), newConfigRef()) var ast = parseFile(conf.projectMainIdx.FileIndex, newIdentCache(), conf)
if ast == nil: return if ast == nil: return
var d = newDocumentor(gProjectFull, options.gConfigVars) var d = newDocumentor(conf.projectFull, conf)
d.hasToc = true d.hasToc = true
var var
content: Rope content: Rope
@ -871,15 +876,15 @@ proc commandTags*() =
writeRope(stdout, content) writeRope(stdout, content)
else: else:
#echo getOutFile(gProjectFull, TagsExt) #echo getOutFile(gProjectFull, TagsExt)
writeRope(content, getOutFile(gProjectFull, TagsExt), useWarning = false) writeRope(content, getOutFile(conf, conf.projectFull, TagsExt), useWarning = false)
proc commandBuildIndex*() = proc commandBuildIndex*(conf: ConfigRef) =
var content = mergeIndexes(gProjectFull).rope var content = mergeIndexes(conf.projectFull).rope
let code = ropeFormatNamedVars(getConfigVar("doc.file"), ["title", let code = ropeFormatNamedVars(conf, getConfigVar(conf, "doc.file"), ["title",
"tableofcontents", "moduledesc", "date", "time", "tableofcontents", "moduledesc", "date", "time",
"content", "author", "version", "analytics"], "content", "author", "version", "analytics"],
["Index".rope, nil, nil, rope(getDateStr()), ["Index".rope, nil, nil, rope(getDateStr()),
rope(getClockStr()), content, nil, nil, nil]) rope(getClockStr()), content, nil, nil, nil])
# no analytics because context is not available # no analytics because context is not available
writeRope(code, getOutFile("theindex", HtmlExt)) writeRope(code, getOutFile(conf, "theindex", HtmlExt))

4
lib/packages/docutils/rst.nim
View file

@ -43,8 +43,8 @@ type
mwUnsupportedField mwUnsupportedField
MsgHandler* = proc (filename: string, line, col: int, msgKind: MsgKind, MsgHandler* = proc (filename: string, line, col: int, msgKind: MsgKind,
arg: string) {.nimcall.} ## what to do in case of an error arg: string) {.closure.} ## what to do in case of an error
FindFileHandler* = proc (filename: string): string {.nimcall.} FindFileHandler* = proc (filename: string): string {.closure.}
const const
messages: array[MsgKind, string] = [ messages: array[MsgKind, string] = [