diff options
| -rw-r--r-- | compiler/docgen.nim | 33 | ||||
| -rw-r--r-- | compiler/docgen2.nim | 3 | ||||
| -rw-r--r-- | compiler/typesrenderer.nim | 5 | ||||
| -rw-r--r-- | config/nimdoc.cfg | 14 | ||||
| -rw-r--r-- | doc/nimdoc.css | 20 | ||||
| -rw-r--r-- | nimdoc/test_out_index_dot_html/expected/index.html | 5 | ||||
| -rw-r--r-- | nimdoc/testproject/expected/subdir/subdir_b/utils.html | 5 | ||||
| -rw-r--r-- | nimdoc/testproject/expected/testproject.html | 208 |
8 files changed, 220 insertions, 73 deletions
diff --git a/compiler/docgen.nim b/compiler/docgen.nim index c2ce12e50..fb15f3826 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 438417ca0..9cb40a7fc 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 050a057f4..613173252 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..<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 = "" diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg index 9a56fdaae..a6a402bab 100644 --- 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: diff --git a/doc/nimdoc.css b/doc/nimdoc.css index fb9efd858..e0c5a1de4 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 f35334503..d6e318f7d 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() { <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> diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.html b/nimdoc/testproject/expected/subdir/subdir_b/utils.html index eefbcfdf9..ebbedc648 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() { <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> diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html index 479a2e89d..9c06211c9 100644 --- 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> |