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

Author: narimiran

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:

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:

compiler/typesrenderer.nim

@@ -78,6 +78,11 @@ proc renderType(n: PNode): string =
     result = renderType(n[0]) & '['
     for i in 1..<n.len: result.add(renderType(n[i]) & ',')
     result[^1] = ']'
+  of nkCommand:
+    result = renderType(n[0])
+    for i in 1..<n.len:
+      if i > 1: result.add ", "
+      result.add(renderType(n[i]))
   else: result = ""
 
 

config/nimdoc.cfg

@@ -24,6 +24,12 @@ doc.section.toc = """
 </li>
 """
 
+doc.section.toc2 = """
+  <ul class="simple nested-toc-section">$plainName
+    $content
+  </ul>
+"""
+
 # 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<span class="attachedType">$attype</span></a></li>
 """
 
+# This is used for TOC items which are grouped by the same name (e.g. procs).
+doc.item.tocTable = """
+  <li><a class="reference" href="#$itemSymOrIDEnc"
+    title="$header_plain">$itemSymOrID<span class="attachedType">$attype</span></a></li>
+"""
+
+
+
 # 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:

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; }

nimdoc/test_out_index_dot_html/expected/index.html

@@ -94,8 +94,11 @@ <h1 class="title">foo</h1>
 <li>
   <a class="reference reference-toplevel" href="#12" id="62">Procs</a>
   <ul class="simple simple-toc-section">
+      <ul class="simple nested-toc-section">foo
       <li><a class="reference" href="#foo"
-    title="foo()"><wbr />foo<span class="attachedType"></span></a></li>
+    title="foo()">foo<span class="attachedType"></span></a></li>
+
+  </ul>
 
   </ul>
 </li>

nimdoc/testproject/expected/subdir/subdir_b/utils.html

@@ -108,8 +108,11 @@ <h1 class="title">subdir/subdir_b/utils</h1>
 <li>
   <a class="reference reference-toplevel" href="#12" id="62">Procs</a>
   <ul class="simple simple-toc-section">
+      <ul class="simple nested-toc-section">someType
       <li><a class="reference" href="#someType_2"
-    title="someType(): SomeType"><wbr />some<wbr />Type<span class="attachedType">SomeType</span></a></li>
+    title="someType(): SomeType">someType_2<span class="attachedType">SomeType</span></a></li>
+
+  </ul>
 
   </ul>
 </li>