From 112b11c154af1f56b8c842b5723e6097d40d9e60 Mon Sep 17 00:00:00 2001 From: Miran Date: Mon, 5 Oct 2020 17:03:14 +0200 Subject: [PATCH] group procs of the same name in TOC (#15487) * group procs of the same name in TOC * correctly show `sink` parameters in TOC * no need to reinvent the wheel - `mgetorPut` exists * better setting of text color [ci skip] * fix CSS for better alignment --- compiler/docgen.nim | 33 ++- compiler/docgen2.nim | 3 +- compiler/typesrenderer.nim | 5 + config/nimdoc.cfg | 14 ++ doc/nimdoc.css | 20 +- .../expected/index.html | 5 +- .../expected/subdir/subdir_b/utils.html | 5 +- nimdoc/testproject/expected/testproject.html | 208 +++++++++++++----- 8 files changed, 220 insertions(+), 73 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index c2ce12e502..fb15f38267 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -37,7 +37,8 @@ type modDesc: Rope # module description module: PSym modDeprecationMsg: Rope - toc, section: TSections + toc, toc2, section: TSections + tocTable: array[TSymKind, Table[string, Rope]] indexValFilename: string analytics: string # Google Analytics javascript, "" if doesn't exist seenSymbols: StringTableRef # avoids duplicate symbol generation for HTML. @@ -871,6 +872,14 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) = itemIDRope, plainNameRope, plainSymbolRope, symbolOrIdRope, plainSymbolEncRope, symbolOrIdEncRope, attype])) + d.tocTable[k].mgetOrPut(cleanPlainSymbol, nil).add(ropeFormatNamedVars( + d.conf, getConfigVar(d.conf, "doc.item.tocTable"), + ["name", "header", "desc", "itemID", "header_plain", "itemSym", + "itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "attype"], + [rope(getName(d, nameNode, d.splitAfter)), result, comm, + itemIDRope, plainNameRope, plainSymbolRope, + symbolOrIdRope, plainSymbolEncRope, symbolOrIdEncRope, attype])) + # Ironically for types the complexSymbol is *cleaner* than the plainName # because it doesn't include object fields or documentation comments. So we # use the plain one for callable elements, and the complex for the rest. @@ -1167,7 +1176,7 @@ proc generateTags*(d: PDoc, n: PNode, r: var Rope) = generateTags(d, lastSon(n[0]), r) else: discard -proc genSection(d: PDoc, kind: TSymKind) = +proc genSection(d: PDoc, kind: TSymKind, groupedToc = false) = const sectionNames: array[skModule..skField, string] = [ "Imports", "Types", "Vars", "Lets", "Consts", "Vars", "Procs", "Funcs", "Methods", "Iterators", "Converters", "Macros", "Templates", "Exports" @@ -1177,14 +1186,23 @@ proc genSection(d: PDoc, kind: TSymKind) = d.section[kind] = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.section"), [ "sectionid", "sectionTitle", "sectionTitleID", "content"], [ ord(kind).rope, title, rope(ord(kind) + 50), d.section[kind]]) + + var tocSource = d.toc + if groupedToc: + for p in d.tocTable[kind].keys: + d.toc2[kind].add ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.section.toc2"), [ + "sectionid", "sectionTitle", "sectionTitleID", "content", "plainName"], [ + ord(kind).rope, title, rope(ord(kind) + 50), d.tocTable[kind][p], p.rope]) + tocSource = d.toc2 + d.toc[kind] = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.section.toc"), [ "sectionid", "sectionTitle", "sectionTitleID", "content"], [ - ord(kind).rope, title, rope(ord(kind) + 50), d.toc[kind]]) + ord(kind).rope, title, rope(ord(kind) + 50), tocSource[kind]]) proc relLink(outDir: AbsoluteDir, destFile: AbsoluteFile, linkto: RelativeFile): Rope = rope($relativeTo(outDir / linkto, destFile.splitFile().dir, '/')) -proc genOutFile(d: PDoc): Rope = +proc genOutFile(d: PDoc, groupedToc = false): Rope = var code, content: Rope title = "" @@ -1193,7 +1211,8 @@ proc genOutFile(d: PDoc): Rope = renderTocEntries(d[], j, 1, tmp) var toc = tmp.rope for i in TSymKind: - genSection(d, i) + var shouldSort = i in {skProc, skFunc} and groupedToc + genSection(d, i, shouldSort) toc.add(d.toc[i]) if toc != nil: toc = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.toc"), ["content"], [toc]) @@ -1246,9 +1265,9 @@ proc updateOutfile(d: PDoc, outfile: AbsoluteFile) = if isAbsolute(d.conf.outFile.string): d.conf.outFile = splitPath(d.conf.outFile.string)[1].RelativeFile -proc writeOutput*(d: PDoc, useWarning = false) = +proc writeOutput*(d: PDoc, useWarning = false, groupedToc = false) = runAllExamples(d) - var content = genOutFile(d) + var content = genOutFile(d, groupedToc) if optStdout in d.conf.globalOptions: writeRope(stdout, content) else: diff --git a/compiler/docgen2.nim b/compiler/docgen2.nim index 438417ca02..9cb40a7fc5 100644 --- a/compiler/docgen2.nim +++ b/compiler/docgen2.nim @@ -29,6 +29,7 @@ proc shouldProcess(g: PGen): bool = template closeImpl(body: untyped) {.dirty.} = var g = PGen(p) let useWarning = sfMainModule notin g.module.flags + let groupedToc = true if shouldProcess(g): body try: @@ -38,7 +39,7 @@ template closeImpl(body: untyped) {.dirty.} = proc close(graph: ModuleGraph; p: PPassContext, n: PNode): PNode = closeImpl: - writeOutput(g.doc, useWarning) + writeOutput(g.doc, useWarning, groupedToc) proc closeJson(graph: ModuleGraph; p: PPassContext, n: PNode): PNode = closeImpl: diff --git a/compiler/typesrenderer.nim b/compiler/typesrenderer.nim index 050a057f4e..6131732525 100644 --- a/compiler/typesrenderer.nim +++ b/compiler/typesrenderer.nim @@ -78,6 +78,11 @@ proc renderType(n: PNode): string = result = renderType(n[0]) & '[' for i in 1.. 1: result.add ", " + result.add(renderType(n[i])) else: result = "" diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg index 9a56fdaaef..a6a402baba 100644 --- a/config/nimdoc.cfg +++ b/config/nimdoc.cfg @@ -24,6 +24,12 @@ doc.section.toc = """ """ +doc.section.toc2 = """ + +""" + # Chunk of HTML emitted for each entry in the HTML table of contents. # Available variables are: # * $desc: the actual docstring of the item. @@ -54,6 +60,14 @@ doc.item.toc = """ title="$header_plain">$name$attype """ +# This is used for TOC items which are grouped by the same name (e.g. procs). +doc.item.tocTable = """ +
  • $itemSymOrID$attype
    • +""" + + + # HTML rendered for doc.item's seeSrc variable. Note that this will render to # the empty string if you don't pass anything through --git.url. Available # substitutaion variables here are: diff --git a/doc/nimdoc.css b/doc/nimdoc.css index fb9efd858f..e0c5a1de4b 100644 --- a/doc/nimdoc.css +++ b/doc/nimdoc.css @@ -154,10 +154,12 @@ body { margin-left: 0; } .three.columns { - width: 19%; } + width: 22%; + line-break: anywhere; +} .nine.columns { - width: 80.0%; } + width: 77.0%; } .twelve.columns { width: 100%; @@ -420,7 +422,7 @@ ul.simple-boot li { } ol.simple > li, ul.simple > li { - margin-bottom: 0.25em; + margin-bottom: 0.2em; margin-left: 0.4em } ul.simple.simple-toc > li { @@ -439,9 +441,19 @@ ul.simple-toc > li { ul.simple-toc-section { list-style-type: circle; - margin-left: 1em; + margin-left: 0.8em; color: #6c9aae; } +ul.nested-toc-section { + list-style-type: circle; + margin-left: -0.75em; + color: var(--text); +} + +ul.nested-toc-section > li { + margin-left: 1.25em; +} + ol.arabic { list-style: decimal; } diff --git a/nimdoc/test_out_index_dot_html/expected/index.html b/nimdoc/test_out_index_dot_html/expected/index.html index f353345037..d6e318f7d2 100644 --- a/nimdoc/test_out_index_dot_html/expected/index.html +++ b/nimdoc/test_out_index_dot_html/expected/index.html @@ -94,8 +94,11 @@ function main() {
  • Procs
      +
        foo
      • foo
        • + title="foo()">foo + +
    • diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.html b/nimdoc/testproject/expected/subdir/subdir_b/utils.html index eefbcfdf94..ebbedc648a 100644 --- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html +++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html @@ -108,8 +108,11 @@ function main() {
  • Procs
      +
        someType
      • someTypeSomeType
        • + title="someType(): SomeType">someType_2SomeType + +
    • diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html index 479a2e89d8..9c06211c97 100644 --- a/nimdoc/testproject/expected/testproject.html +++ b/nimdoc/testproject/expected/testproject.html @@ -137,74 +137,164 @@ function main() {
  • Procs
  • Funcs
      +
        someFunc
      • someFunc
        • + title="someFunc()">someFunc + +