docgen: implement cross-document links (#20990)
* docgen: implement cross-document links Fully implements https://github.com/nim-lang/RFCs/issues/125 Follow-up of: https://github.com/nim-lang/Nim/pull/18642 (for internal links) and https://github.com/nim-lang/Nim/issues/20127. Overview -------- Explicit import-like directive is required, called `.. importdoc::`. (the syntax is % RST, Markdown will use it for a while). Then one can reference any symbols/headings/anchors, as if they were in the local file (but they will be prefixed with a module name or markup document in link text). It's possible to reference anything from anywhere (any direction in `.nim`/`.md`/`.rst` files). See `doc/docgen.md` for full description. Working is based on `.idx` files, hence one needs to generate all `.idx` beforehand. A dedicated option `--index:only` is introduced (and a separate stage for `--index:only` is added to `kochdocs.nim`). Performance note ---------------- Full run for `./koch docs` now takes 185% of the time before this PR. (After: 315 s, before: 170 s on my PC). All the time seems to be spent on `--index:only` run, which takes almost as much (85%) of normal doc run -- it seems that most time is spent on file parsing, turning off HTML generation phase has not helped much. (One could avoid it by specifying list of files that can be referenced and pre-processing only them. But it can become error-prone and I assume that these linke will be **everywhere** in the repository anyway, especially considering https://github.com/nim-lang/RFCs/issues/478. So every `.nim`/`.md` file is processed for `.idx` first). But that's all without significant part of repository converted to cross-module auto links. To estimate impact I checked the time for `doc`ing a few files (after all indexes have been generated), and everywhere difference was **negligible**. E.g. for `lib/std/private/osfiles.nim` that `importdoc`s large `os.idx` and hence should have been a case with relatively large performance impact, but: * After: 0.59 s. * Before: 0.59 s. So Nim compiler works so slow that doc part basically does not matter :-) Testing ------- 1) added `extlinks` test to `nimdoc/` 2) checked that `theindex.html` is still correct 2) fixed broken auto-links for modules that were derived from `os.nim` by adding appropriate ``importdoc`` Implementation note ------------------- Parsing and formating of `.idx` entries is moved into a dedicated `rstidx.nim` module from `rstgen.nim`. `.idx` file format changed: * fields are not escaped in most cases because we need original strings for referencing, not HTML ones (the exception is linkTitle for titles and headings). Escaping happens later -- on the stage of `rstgen` buildIndex, etc. * all lines have fixed number of columns 6 * added discriminator tag as a first column, it always allows distinguish Nim/markup entries, titles/headings, etc. `rstgen` does not rely any more (in most cases) on ad-hoc logic to determine what type each entry is. * there is now always a title entry added at the first line. * add a line number as 6th column * linkTitle (4th) column has a different format: before it was like `module: funcName()`, now it's `proc funcName()`. (This format is also propagated to `theindex.html` and search results, I kept it that way since I like it more though it's discussible.) This column is what used for Nim symbols resolution. * also changed details on column format for headings and titles: "keyword" is original, "linkTitle" is HTML one * fix paths on Windows + more clear code * Update compiler/docgen.nim Co-authored-by: Andreas Rumpf <rumpf_a@web.de> * Handle .md and .nim paths uniformly in findRefFile * handle titles better + more comments * don't allow markup overwrite index title for .nim files Co-authored-by: Andreas Rumpf <rumpf_a@web.de>
This commit is contained in:
Andrey Makarov
GitHub
parent
b2328b44ba
commit
2620da9bf9
45 changed files with 1863 additions and 491 deletions
|
|
@ -1,64 +1,67 @@
|
|||
someVariable testproject.html#someVariable testproject: someVariable
|
||||
C_A testproject.html#C_A testproject: C_A
|
||||
C_B testproject.html#C_B testproject: C_B
|
||||
C_C testproject.html#C_C testproject: C_C
|
||||
C_D testproject.html#C_D testproject: C_D
|
||||
bar testproject.html#bar,T,T testproject: bar[T](a, b: T): T
|
||||
baz testproject.html#baz,T,T testproject: baz[T](a, b: T): T
|
||||
buzz testproject.html#buzz,T,T testproject: buzz[T](a, b: T): T
|
||||
FooBuzz testproject.html#FooBuzz testproject: FooBuzz
|
||||
bar testproject.html#bar testproject: bar(f: FooBuzz)
|
||||
aVariable testproject.html#aVariable testproject: aVariable
|
||||
A testproject.html#A testproject: A
|
||||
B testproject.html#B testproject: B
|
||||
someFunc testproject.html#someFunc testproject: someFunc()
|
||||
fromUtils1 testproject.html#fromUtils1.i testproject: fromUtils1(): int
|
||||
fromUtils2 testproject.html#fromUtils2.t testproject: fromUtils2()
|
||||
fromUtils3 testproject.html#fromUtils3 testproject: fromUtils3()
|
||||
isValid testproject.html#isValid,T testproject: isValid[T](x: T): bool
|
||||
enumValueA2 testproject.html#enumValueA2 Foo.enumValueA2
|
||||
Foo testproject.html#Foo testproject: Foo
|
||||
z1 testproject.html#z1 testproject: z1(): Foo
|
||||
z2 testproject.html#z2 testproject: z2()
|
||||
z3 testproject.html#z3 testproject: z3()
|
||||
z4 testproject.html#z4 testproject: z4()
|
||||
z5 testproject.html#z5 testproject: z5(): int
|
||||
z6 testproject.html#z6 testproject: z6(): int
|
||||
z6t testproject.html#z6t.t testproject: z6t(): int
|
||||
z7 testproject.html#z7 testproject: z7(): int
|
||||
z8 testproject.html#z8 testproject: z8(): int
|
||||
z9 testproject.html#z9 testproject: z9()
|
||||
z10 testproject.html#z10 testproject: z10()
|
||||
z11 testproject.html#z11 testproject: z11()
|
||||
z12 testproject.html#z12 testproject: z12(): int
|
||||
z13 testproject.html#z13 testproject: z13()
|
||||
baz testproject.html#baz testproject: baz()
|
||||
z17 testproject.html#z17 testproject: z17()
|
||||
p1 testproject.html#p1 testproject: p1()
|
||||
addfBug14485 testproject.html#addfBug14485 testproject: addfBug14485()
|
||||
c_printf testproject.html#c_printf,cstring testproject: c_printf(frmt: cstring): cint
|
||||
c_nonexistent testproject.html#c_nonexistent,cstring testproject: c_nonexistent(frmt: cstring): cint
|
||||
low testproject.html#low,T testproject: low[T: Ordinal | enum | range](x: T): T
|
||||
low2 testproject.html#low2,T testproject: low2[T: Ordinal | enum | range](x: T): T
|
||||
tripleStrLitTest testproject.html#tripleStrLitTest testproject: tripleStrLitTest()
|
||||
method1 testproject.html#method1.e,Moo testproject: method1(self: Moo)
|
||||
method2 testproject.html#method2.e,Moo testproject: method2(self: Moo): int
|
||||
method3 testproject.html#method3.e,Moo testproject: method3(self: Moo): int
|
||||
iter1 testproject.html#iter1.i,int testproject: iter1(n: int): int
|
||||
iter2 testproject.html#iter2.i,int testproject: iter2(n: int): int
|
||||
bar testproject.html#bar.m testproject: bar(): untyped
|
||||
z16 testproject.html#z16.m testproject: z16()
|
||||
z18 testproject.html#z18.m testproject: z18(): int
|
||||
foo testproject.html#foo.t,SomeType,SomeType testproject: foo(a, b: SomeType)
|
||||
myfn testproject.html#myfn.t testproject: myfn()
|
||||
z14 testproject.html#z14.t testproject: z14()
|
||||
z15 testproject.html#z15.t testproject: z15()
|
||||
asyncFun1 testproject.html#asyncFun1 testproject: asyncFun1(): Future[int]
|
||||
asyncFun2 testproject.html#asyncFun2 testproject: asyncFun2(): owned(Future[void])
|
||||
asyncFun3 testproject.html#asyncFun3 testproject: asyncFun3(): owned(Future[void])
|
||||
testNimDocTrailingExample testproject.html#testNimDocTrailingExample.t testproject: testNimDocTrailingExample()
|
||||
Circle testproject.html#Circle Shapes.Circle
|
||||
Triangle testproject.html#Triangle Shapes.Triangle
|
||||
Rectangle testproject.html#Rectangle Shapes.Rectangle
|
||||
Shapes testproject.html#Shapes testproject: Shapes
|
||||
anything testproject.html#anything testproject: anything()
|
||||
nimTitle testproject testproject.html module testproject 0
|
||||
nim someVariable testproject.html#someVariable var someVariable 13
|
||||
nim C_A testproject.html#C_A const C_A 26
|
||||
nim C_B testproject.html#C_B const C_B 27
|
||||
nim C_C testproject.html#C_C const C_C 28
|
||||
nim C_D testproject.html#C_D const C_D 29
|
||||
nim bar testproject.html#bar,T,T proc bar[T](a, b: T): T 31
|
||||
nim baz testproject.html#baz,T,T proc baz[T](a, b: T): T 34
|
||||
nim buzz testproject.html#buzz,T,T proc buzz[T](a, b: T): T 38
|
||||
nim FooBuzz testproject.html#FooBuzz type FooBuzz 43
|
||||
nim bar testproject.html#bar proc bar(f: FooBuzz) 47
|
||||
nim aVariable testproject.html#aVariable var aVariable 52
|
||||
nim A testproject.html#A enum A 92
|
||||
nim B testproject.html#B enum B 97
|
||||
nim someFunc testproject.html#someFunc proc someFunc() 56
|
||||
nim fromUtils1 testproject.html#fromUtils1.i iterator fromUtils1(): int 112
|
||||
nim fromUtils2 testproject.html#fromUtils2.t template fromUtils2() 119
|
||||
nim fromUtils3 testproject.html#fromUtils3 proc fromUtils3() 57
|
||||
nim isValid testproject.html#isValid,T proc isValid[T](x: T): bool 59
|
||||
nim enumValueA2 testproject.html#enumValueA2 Foo.enumValueA2 66
|
||||
nim Foo testproject.html#Foo enum Foo 66
|
||||
nim z1 testproject.html#z1 proc z1(): Foo 69
|
||||
nim z2 testproject.html#z2 proc z2() 73
|
||||
nim z3 testproject.html#z3 proc z3() 78
|
||||
nim z4 testproject.html#z4 proc z4() 81
|
||||
nim z5 testproject.html#z5 proc z5(): int 87
|
||||
nim z6 testproject.html#z6 proc z6(): int 91
|
||||
nim z6t testproject.html#z6t.t template z6t(): int 95
|
||||
nim z7 testproject.html#z7 proc z7(): int 99
|
||||
nim z8 testproject.html#z8 proc z8(): int 103
|
||||
nim z9 testproject.html#z9 proc z9() 111
|
||||
nim z10 testproject.html#z10 proc z10() 114
|
||||
nim z11 testproject.html#z11 proc z11() 119
|
||||
nim z12 testproject.html#z12 proc z12(): int 124
|
||||
nim z13 testproject.html#z13 proc z13() 129
|
||||
nim baz testproject.html#baz proc baz() 134
|
||||
nim z17 testproject.html#z17 proc z17() 144
|
||||
nim p1 testproject.html#p1 proc p1() 156
|
||||
nim addfBug14485 testproject.html#addfBug14485 proc addfBug14485() 177
|
||||
nim c_printf testproject.html#c_printf,cstring proc c_printf(frmt: cstring): cint 193
|
||||
nim c_nonexistent testproject.html#c_nonexistent,cstring proc c_nonexistent(frmt: cstring): cint 197
|
||||
nim low testproject.html#low,T proc low[T: Ordinal | enum | range](x: T): T 200
|
||||
nim low2 testproject.html#low2,T proc low2[T: Ordinal | enum | range](x: T): T 210
|
||||
nim tripleStrLitTest testproject.html#tripleStrLitTest proc tripleStrLitTest() 223
|
||||
nim method1 testproject.html#method1.e,Moo method method1(self: Moo) 264
|
||||
nim method2 testproject.html#method2.e,Moo method method2(self: Moo): int 266
|
||||
nim method3 testproject.html#method3.e,Moo method method3(self: Moo): int 269
|
||||
nim iter1 testproject.html#iter1.i,int iterator iter1(n: int): int 274
|
||||
nim iter2 testproject.html#iter2.i,int iterator iter2(n: int): int 278
|
||||
nim bar testproject.html#bar.m macro bar(): untyped 285
|
||||
nim z16 testproject.html#z16.m macro z16() 288
|
||||
nim z18 testproject.html#z18.m macro z18(): int 297
|
||||
nim foo testproject.html#foo.t,SomeType,SomeType template foo(a, b: SomeType) 302
|
||||
nim myfn testproject.html#myfn.t template myfn() 307
|
||||
nim z14 testproject.html#z14.t template z14() 328
|
||||
nim z15 testproject.html#z15.t template z15() 333
|
||||
nim asyncFun1 testproject.html#asyncFun1 proc asyncFun1(): Future[int] 358
|
||||
nim asyncFun2 testproject.html#asyncFun2 proc asyncFun2(): owned(Future[void]) 361
|
||||
nim asyncFun3 testproject.html#asyncFun3 proc asyncFun3(): owned(Future[void]) 362
|
||||
nim testNimDocTrailingExample testproject.html#testNimDocTrailingExample.t template testNimDocTrailingExample() 371
|
||||
nim Circle testproject.html#Circle Shapes.Circle 380
|
||||
nim Triangle testproject.html#Triangle Shapes.Triangle 380
|
||||
nim Rectangle testproject.html#Rectangle Shapes.Rectangle 380
|
||||
nim Shapes testproject.html#Shapes enum Shapes 380
|
||||
nim anything testproject.html#anything proc anything() 387
|
||||
nimgrp bar testproject.html#bar-procs-all proc 31
|
||||
nimgrp baz testproject.html#baz-procs-all proc 34
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue