From 7d217a71d3679b58f74bb134add20d9b80750341 Mon Sep 17 00:00:00 2001 From: LemonBoy Date: Mon, 3 Jun 2019 10:15:20 +0200 Subject: [PATCH] Render deprecated pragmas (#8886) * Render deprecated pragmas * fix the expected html * clean up the documentation regarding deprecations * fix typo * fix system.nim * fix random --- compiler/docgen.nim | 43 ++++++++++++--- compiler/trees.nim | 6 ++ config/nimdoc.cfg | 10 ++++ lib/core/macros.nim | 55 +++++++++---------- lib/impure/re.nim | 4 +- lib/pure/algorithm.nim | 5 +- lib/pure/asyncdispatch.nim | 5 +- lib/pure/collections/heapqueue.nim | 8 +-- lib/pure/collections/sets.nim | 9 +-- lib/pure/collections/sharedlist.nim | 3 +- lib/pure/collections/sharedtables.nim | 4 +- lib/pure/json.nim | 16 +++--- lib/pure/math.nim | 20 +++---- lib/pure/nativesockets.nim | 8 +-- lib/pure/random.nim | 30 ++++------ lib/system.nim | 15 +---- .../expected/index.html | 2 + .../expected/subdir/subdir_b/utils.html | 5 ++ nimdoc/testproject/expected/testproject.html | 33 +++++++++++ nimdoc/testproject/expected/theindex.html | 8 +++ nimdoc/testproject/testproject.nim | 8 +++ 21 files changed, 180 insertions(+), 117 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 350487d31..a9ecf2b4c 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -17,7 +17,7 @@ import packages/docutils/rst, packages/docutils/rstgen, packages/docutils/highlite, json, xmltree, cgi, trees, types, typesrenderer, astalgo, modulepaths, lineinfos, sequtils, intsets, - pathutils + pathutils, trees const exportSection = skField @@ -25,7 +25,8 @@ const type TSections = array[TSymKind, Rope] TDocumentor = object of rstgen.RstGenerator - modDesc: Rope # module description + modDesc: Rope # module description + modDeprecationMsg: Rope toc, section: TSections indexValFilename: string analytics: string # Google Analytics javascript, "" if doesn't exist @@ -610,6 +611,23 @@ proc docstringSummary(rstText: string): string = result.delete(pos, last) result.add("…") +proc genDeprecationMsg(d: PDoc, n: PNode): Rope = + ## Given a nkPragma wDeprecated node output a well-formatted section + if n == nil: return + + case n.safeLen: + of 0: # Deprecated w/o any message + result = ropeFormatNamedVars(d.conf, + getConfigVar(d.conf, "doc.deprecationmsg"), ["label", "message"], + [~"Deprecated", nil]) + of 2: # Deprecated w/ a message + if n[1].kind in {nkStrLit..nkTripleStrLit}: + result = ropeFormatNamedVars(d.conf, + getConfigVar(d.conf, "doc.deprecationmsg"), ["label", "message"], + [~"Deprecated:", rope(xmltree.escape(n[1].strVal))]) + else: + doAssert false + proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) = if not isVisible(d, nameNode): return let @@ -631,6 +649,10 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) = break plainName.add(literal) + var pragmaNode: PNode = nil + if n.isCallable and n.sons[pragmasPos].kind != nkEmpty: + pragmaNode = findPragma(n.sons[pragmasPos], wDeprecated) + inc(d.id) let plainNameRope = rope(xmltree.escape(plainName.strip)) @@ -642,6 +664,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) = symbolOrId = d.newUniquePlainSymbol(complexSymbol) symbolOrIdRope = symbolOrId.rope symbolOrIdEncRope = encodeUrl(symbolOrId).rope + deprecationMsgRope = genDeprecationMsg(d, pragmaNode) nodeToHighlightedHtml(d, n, result, {renderNoBody, renderNoComments, renderDocComments, renderSyms}, symbolOrIdEncRope) @@ -666,9 +689,10 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) = add(d.section[k], ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.item"), ["name", "header", "desc", "itemID", "header_plain", "itemSym", - "itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "seeSrc"], + "itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "seeSrc", "deprecationMsg"], [nameRope, result, comm, itemIDRope, plainNameRope, plainSymbolRope, - symbolOrIdRope, plainSymbolEncRope, symbolOrIdEncRope, seeSrcRope])) + symbolOrIdRope, plainSymbolEncRope, symbolOrIdEncRope, seeSrcRope, + deprecationMsgRope])) let external = d.destFile.relativeTo(d.conf.outDir, '/').changeFileExt(HtmlExt).string @@ -821,6 +845,9 @@ proc documentRaises*(cache: IdentCache; n: PNode) = proc generateDoc*(d: PDoc, n, orig: PNode) = case n.kind + of nkPragma: + let pragmaNode = findPragma(n, wDeprecated) + add(d.modDeprecationMsg, genDeprecationMsg(d, pragmaNode)) of nkCommentStmt: add(d.modDesc, genComment(d, n)) of nkProcDef: when useEffectSystem: documentRaises(d.cache, n) @@ -993,17 +1020,17 @@ proc genOutFile(d: PDoc): Rope = elif d.hasToc: "doc.body_toc" else: "doc.body_no_toc" content = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, bodyname), ["title", - "tableofcontents", "moduledesc", "date", "time", "content"], + "tableofcontents", "moduledesc", "date", "time", "content", "deprecationMsg"], [title.rope, toc, d.modDesc, rope(getDateStr()), - rope(getClockStr()), code]) + rope(getClockStr()), code, d.modDeprecationMsg]) if optCompileOnly notin d.conf.globalOptions: # XXX what is this hack doing here? 'optCompileOnly' means raw output!? code = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.file"), ["title", "tableofcontents", "moduledesc", "date", "time", - "content", "author", "version", "analytics"], + "content", "author", "version", "analytics", "deprecationMsg"], [title.rope, toc, d.modDesc, rope(getDateStr()), rope(getClockStr()), content, d.meta[metaAuthor].rope, - d.meta[metaVersion].rope, d.analytics.rope]) + d.meta[metaVersion].rope, d.analytics.rope, d.modDeprecationMsg]) else: code = content result = code diff --git a/compiler/trees.nim b/compiler/trees.nim index c1adee863..c878eb1bf 100644 --- a/compiler/trees.nim +++ b/compiler/trees.nim @@ -120,6 +120,12 @@ proc whichPragma*(n: PNode): TSpecialWord = let key = if n.kind in nkPragmaCallKinds and n.len > 0: n.sons[0] else: n if key.kind == nkIdent: result = whichKeyword(key.ident) +proc findPragma*(n: PNode, which: TSpecialWord): PNode = + if n.kind == nkPragma: + for son in n: + if whichPragma(son) == which: + return son + proc effectSpec*(n: PNode, effectType: TSpecialWord): PNode = for i in 0 ..< sonsLen(n): var it = n.sons[i] diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg index 701bd55ed..a2860af14 100644 --- a/config/nimdoc.cfg +++ b/config/nimdoc.cfg @@ -41,6 +41,7 @@ doc.item = """ 
$header
+$deprecationMsg $desc $seeSrc
@@ -68,6 +69,12 @@ class="link-seesrc" target="_blank">Source Edit """ +doc.deprecationmsg = """ +
+ $label $message +
+""" + doc.toc = """