enable compiler docs with their own index+search (#14493)

* enable compiler docs (with its own index)

tools/kochdocs.nim

@@ -5,8 +5,7 @@ import "../compiler/nimpaths"
 
 const
   gaCode* = " --doc.googleAnalytics:UA-48159761-1"
-  # --warning[LockLevel]:off pending #13218
+  nimArgs = "--hint:Conf:off --hint:Path:off --hint:Processing:off -d:boot --putenv:nimversion=$#" % system.NimVersion
-  nimArgs = "--warning[LockLevel]:off --hint[Conf]:off --hint[Path]:off --hint[Processing]:off -d:boot --putenv:nimversion=$#" % system.NimVersion
   gitUrl = "https://github.com/nim-lang/Nim"
   docHtmlOutput = "doc/html"
   webUploadOutput = "web/upload"
@@ -231,6 +230,15 @@ proc buildDocSamples(nimArgs, destPath: string) =
   exec(findNim().quoteShell() & " doc $# -o:$# $#" %
     [nimArgs, destPath / "docgen_sample.html", "doc" / "docgen_sample.nim"])
 
+proc buildDocPackages(nimArgs, destPath: string) =
+  # compiler docs, and later, other packages (perhaps tools, testament etc)
+  let nim = findNim().quoteShell()
+  let extra = "-u:boot"
+    # to avoid broken links to manual from compiler dir, but a multi-package
+    # structure could be supported later
+  exec("$1 doc --project --outdir:$2/compiler $3 --git.url:$4 $5 compiler/nim.nim" %
+    [nim, destPath, nimArgs, gitUrl, extra])
+
 proc buildDoc(nimArgs, destPath: string) =
   # call nim for the documentation:
   var
@@ -249,8 +257,7 @@ proc buildDoc(nimArgs, destPath: string) =
     i.inc
   for d in items(doc):
     var nimArgs2 = nimArgs
-    if d.isRelativeTo("compiler"):
+    if d.isRelativeTo("compiler"): doAssert false
-      nimArgs2.add " --docroot"
     commands[i] = nim & " doc $# --git.url:$# --outdir:$# --index:on $#" %
       [nimArgs2, gitUrl, destPath, d]
     i.inc
@@ -262,6 +269,11 @@ proc buildDoc(nimArgs, destPath: string) =
 
   mexec(commands)
   exec(nim & " buildIndex -o:$1/theindex.html $1" % [destPath])
+    # caveat: this works so long it's called before `buildDocPackages` which
+    # populates `compiler/` with unrelated idx files that shouldn't be in index,
+    # so should work in CI but you may need to remove your generated html files
+    # locally after calling `./koch docs`. The clean fix would be for `idx` files
+    # to be transient with `--project` (eg all in memory).
 
 proc buildPdfDoc*(nimArgs, destPath: string) =
   createDir(destPath)
@@ -296,20 +308,15 @@ proc buildJS(): string =
   result = getDocHacksJs(nimr = getCurrentDir(), nim)
 
 proc buildDocs*(args: string) =
-  let
+  let docHackJsSource = buildJS()
-    a = nimArgs & " " & args
+  template fn(args, dir) =
-    docHackJsSource = buildJS()
+    let dir2 = dir
-    docHackJs = docHackJsSource.lastPathPart
+    let args2 = args
+    createDir(dir2)
+    buildDocSamples(args2, dir2)
+    buildDoc(args2, dir2)
+    buildDocPackages(args2, dir2)
+    copyFile(docHackJsSource, dir2 / docHackJsSource.lastPathPart)
 
-  let docup = webUploadOutput / NimVersion
+  fn(nimArgs & " " & args, webUploadOutput / NimVersion)
-  createDir(docup)
+  fn(nimArgs, docHtmlOutput) # no `args` to avoid offline docs containing the 'gaCode'!
-  buildDocSamples(a, docup)
-  buildDoc(a, docup)
-
-  # 'nimArgs' instead of 'a' is correct here because we don't want
-  # that the offline docs contain the 'gaCode'!
-  createDir(docHtmlOutput)
-  buildDocSamples(nimArgs, docHtmlOutput)
-  buildDoc(nimArgs, docHtmlOutput)
-  copyFile(docHackJsSource, docHtmlOutput / docHackJs)
-  copyFile(docHackJsSource, docup / docHackJs)