--docRoot now has smart default: best among @pkg, @path

compiler/commands.nim

@@ -414,8 +414,7 @@ proc processSwitch*(switch, arg: string, pass: TCmdLinePass, info: TLineInfo;
     expectArg(conf, switch, arg, pass, info)
     conf.docSeeSrcUrl = arg
   of "docroot":
-    expectArg(conf, switch, arg, pass, info)
-    conf.docRoot = arg
+    conf.docRoot = if arg.len == 0: "@default" else: arg
   of "mainmodule", "m":
     discard "allow for backwards compatibility, but don't do anything"
   of "define", "d":

compiler/docgen.nim

@@ -59,15 +59,24 @@ proc presentationPath*(conf: ConfigRef, file: AbsoluteFile, isTitle = false): Re
   let file2 = $file
   template bail() =
     result = relativeTo(file, conf.projectPath)
+  proc nimbleDir(): AbsoluteDir =
+    getNimbleFile(conf, file2).parentDir.AbsoluteDir
   case conf.docRoot:
+  of "@default": # using `@` instead of `$` to avoid shell quoting complications
+    result = getRelativePathFromConfigPath(conf, file)
+    let dir = nimbleDir()
+    if not dir.isEmpty:
+      let result2 = relativeTo(file, dir)
+      if not result2.isEmpty and (result.isEmpty or result2.string.len < result.string.len):
+        result = result2
+    if result.isEmpty: bail()
   of "@pkg":
-    let dir = getNimbleFile(conf, file2).parentDir.AbsoluteDir
+    let dir = nimbleDir()
     if dir.isEmpty: bail()
     else: result = relativeTo(file, dir)
   of "@path":
     result = getRelativePathFromConfigPath(conf, file)
     if result.isEmpty: bail()
-  # we could consider a @besteffort mode that would returned the "best" match among @pkg and @path
   elif conf.docRoot.len > 0:
     doAssert conf.docRoot.isAbsolute, conf.docRoot # or globalError
     doAssert conf.docRoot.existsDir, conf.docRoot

doc/advopt.txt

@@ -71,6 +71,8 @@ Advanced options:
                             generates: docs/sub/main.html
                             if path == @pkg, will use nimble file enclosing dir
                             if path == @path, will use first matching dir in --path
+                            if path == @default (the default and most useful), will use
+                            best match among @pkg,@path.
                             if these are nonexistant, will use project path
   --docSeeSrcUrl:url        activate 'see source' for doc and doc2 commands
                             (see doc.item.seesrc in config/nimdoc.cfg)

tools/kochdocs.nim

@@ -321,7 +321,7 @@ proc buildDoc(nimArgs, destPath: string) =
   for d in items(doc):
     var nimArgs2 = nimArgs
     if d.isRelativeTo("compiler"):
-      nimArgs2.add " --docroot:@pkg"
+      nimArgs2.add " --docroot"
     commands[i] = nim & " doc $# --git.url:$# --outdir:$# --index:on $#" %
       [nimArgs2, gitUrl, destPath, d]
     i.inc