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
2026-07-22 00:41:28 +00:00 · 2020-10-05 17:03:14 +02:00
parent 5967b6f60f
commit 112b11c154
8 changed files with 220 additions and 73 deletions
--- 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:
--- 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:
--- 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..<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 = ""


--- a/config/nimdoc.cfg
+++ b/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:
--- 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; }
--- 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() {
 <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>
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
@@ -108,8 +108,11 @@ function main() {
 <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>
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -137,74 +137,164 @@ function main() {
 <li>
  <a class="reference reference-toplevel" href="#12" id="62">Procs</a>
  <ul class="simple simple-toc-section">
+      <ul class="simple nested-toc-section">z10
+      <li><a class="reference" href="#z10"
+    title="z10()">z10<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">tripleStrLitTest
+      <li><a class="reference" href="#tripleStrLitTest"
+    title="tripleStrLitTest()">tripleStrLitTest<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z17
+      <li><a class="reference" href="#z17"
+    title="z17()">z17<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">asyncFun3
+      <li><a class="reference" href="#asyncFun3"
+    title="asyncFun3(): owned(Future[void])">asyncFun3<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z2
+      <li><a class="reference" href="#z2"
+    title="z2()">z2<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">bar
      <li><a class="reference" href="#bar%2CT%2CT"
-    title="bar[T](a, b: T): T"><wbr />bar<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#baz%2CT%2CT"
-    title="baz[T](a, b: T): T"><wbr />baz<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#buzz%2CT%2CT"
-    title="buzz[T](a, b: T): T"><wbr />buzz<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#fromUtils3"
-    title="fromUtils3()"><wbr />from<wbr />Utils3<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#isValid%2CT"
-    title="isValid[T](x: T): bool"><wbr />is<wbr />Valid<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z1"
-    title="z1(): Foo"><wbr />z1<span class="attachedType">Foo</span></a></li>
-  <li><a class="reference" href="#z2"
-    title="z2()"><wbr />z2<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z3"
-    title="z3()"><wbr />z3<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z4"
-    title="z4()"><wbr />z4<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z5"
-    title="z5(): int"><wbr />z5<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z6"
-    title="z6(): int"><wbr />z6<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z7"
-    title="z7(): int"><wbr />z7<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z8"
-    title="z8(): int"><wbr />z8<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z9"
-    title="z9()"><wbr />z9<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z10"
-    title="z10()"><wbr />z10<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z11"
-    title="z11()"><wbr />z11<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z12"
-    title="z12(): int"><wbr />z12<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z13"
-    title="z13()"><wbr />z13<span class="attachedType"></span></a></li>
+    title="bar[T](a, b: T): T">bar,T,T<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fromUtils3
+      <li><a class="reference" href="#fromUtils3"
+    title="fromUtils3()">fromUtils3<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">isValid
+      <li><a class="reference" href="#isValid%2CT"
+    title="isValid[T](x: T): bool">isValid,T<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z6
+      <li><a class="reference" href="#z6"
+    title="z6(): int">z6<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">low
+      <li><a class="reference" href="#low%2CT"
+    title="low[T: Ordinal | enum | range](x: T): T">low,T<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">p1
+      <li><a class="reference" href="#p1"
+    title="p1()">p1<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z11
+      <li><a class="reference" href="#z11"
+    title="z11()">z11<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">buzz
+      <li><a class="reference" href="#buzz%2CT%2CT"
+    title="buzz[T](a, b: T): T">buzz,T,T<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">low2
+      <li><a class="reference" href="#low2%2CT"
+    title="low2[T: Ordinal | enum | range](x: T): T">low2,T<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z7
+      <li><a class="reference" href="#z7"
+    title="z7(): int">z7<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z13
+      <li><a class="reference" href="#z13"
+    title="z13()">z13<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">baz
+      <li><a class="reference" href="#baz%2CT%2CT"
+    title="baz[T](a, b: T): T">baz,T,T<span class="attachedType"></span></a></li>
  <li><a class="reference" href="#baz"
-    title="baz()"><wbr />baz<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#z17"
-    title="z17()"><wbr />z17<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#p1"
-    title="p1()"><wbr />p1<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#addfBug14485"
-    title="addfBug14485()"><wbr />addf<wbr />Bug14485<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#c_printf%2Ccstring"
-    title="c_printf(frmt: cstring): cint"><wbr />c_<wbr />printf<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#c_nonexistant%2Ccstring"
-    title="c_nonexistant(frmt: cstring): cint"><wbr />c_<wbr />nonexistant<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#low%2CT"
-    title="low[T: Ordinal | enum | range](x: T): T"><wbr />low<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#low2%2CT"
-    title="low2[T: Ordinal | enum | range](x: T): T"><wbr />low2<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#tripleStrLitTest"
-    title="tripleStrLitTest()"><wbr />triple<wbr />Str<wbr />Lit<wbr />Test<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#asyncFun1"
-    title="asyncFun1(): Future[int]"><wbr />async<wbr />Fun1<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#asyncFun2"
-    title="asyncFun2(): owned(Future[void])"><wbr />async<wbr />Fun2<span class="attachedType"></span></a></li>
-  <li><a class="reference" href="#asyncFun3"
-    title="asyncFun3(): owned(Future[void])"><wbr />async<wbr />Fun3<span class="attachedType"></span></a></li>
+    title="baz()">baz<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">addfBug14485
+      <li><a class="reference" href="#addfBug14485"
+    title="addfBug14485()">addfBug14485<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">c_printf
+      <li><a class="reference" href="#c_printf%2Ccstring"
+    title="c_printf(frmt: cstring): cint">c_printf,cstring<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z12
+      <li><a class="reference" href="#z12"
+    title="z12(): int">z12<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z3
+      <li><a class="reference" href="#z3"
+    title="z3()">z3<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z9
+      <li><a class="reference" href="#z9"
+    title="z9()">z9<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z4
+      <li><a class="reference" href="#z4"
+    title="z4()">z4<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z8
+      <li><a class="reference" href="#z8"
+    title="z8(): int">z8<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z1
+      <li><a class="reference" href="#z1"
+    title="z1(): Foo">z1<span class="attachedType">Foo</span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">z5
+      <li><a class="reference" href="#z5"
+    title="z5(): int">z5<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">asyncFun2
+      <li><a class="reference" href="#asyncFun2"
+    title="asyncFun2(): owned(Future[void])">asyncFun2<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">c_nonexistant
+      <li><a class="reference" href="#c_nonexistant%2Ccstring"
+    title="c_nonexistant(frmt: cstring): cint">c_nonexistant,cstring<span class="attachedType"></span></a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">asyncFun1
+      <li><a class="reference" href="#asyncFun1"
+    title="asyncFun1(): Future[int]">asyncFun1<span class="attachedType"></span></a></li>
+
+  </ul>

  </ul>
 </li>
 <li>
  <a class="reference reference-toplevel" href="#13" id="63">Funcs</a>
  <ul class="simple simple-toc-section">
+      <ul class="simple nested-toc-section">someFunc
      <li><a class="reference" href="#someFunc"
-    title="someFunc()"><wbr />some<wbr />Func<span class="attachedType"></span></a></li>
+    title="someFunc()">someFunc<span class="attachedType"></span></a></li>
+
+  </ul>

  </ul>
 </li>