fixup

changelog.md

@@ -195,6 +195,10 @@ proc mydiv(a, b): int {.raises: [].} =
 - `nim doc foo/main` now outputs to `htmldocs/main.html` (with or without `--project`), like it used to,
   which avoids clobbering either `$PWD` or your source files. Use `--outDir:.` to restore previous behaviour
   or `--usenimcache` to output instead under $nimcache.
+- `nim doc foo/main` now outputs to `$nimcache/htmldocs/main.html` (with or without `--project`),
+- `nim doc foo/main` now outputs to `$nimcache/htmldocs/main.html` instead of $PWD,
+  which avoids clobbering either `$PWD` or your source files. Use `--outDir:.` to restore previous behaviour.
+  It now also generates theindex.html and links the index in the TOC, as well as enables search.
 
 ## Tool changes
 

compiler/docgen.nim

@@ -61,7 +61,7 @@ proc nativeToUnix(path: string): string =
   else: result = path
 
 proc docOutDir(conf: ConfigRef, subdir: RelativeDir = RelativeDir""): AbsoluteDir =
-  result = if not conf.outDir.isEmpty: conf.outDir else: conf.projectPath / subdir
+  if not conf.outDir.isEmpty: conf.outDir else: conf.projectPath / subdir
 
 proc presentationPath*(conf: ConfigRef, file: AbsoluteFile, isTitle = false): RelativeFile =
   ## returns a relative file that will be appended to outDir
@@ -1127,8 +1127,8 @@ proc genSection(d: PDoc, kind: TSymKind) =
       "sectionid", "sectionTitle", "sectionTitleID", "content"], [
       ord(kind).rope, title, rope(ord(kind) + 50), d.toc[kind]])
 
-proc cssHref(outDir: AbsoluteDir, destFile: AbsoluteFile): Rope =
-  rope($relativeTo(outDir / nimdocOutCss.RelativeFile, destFile.splitFile().dir, '/'))
+proc relLink(outDir: AbsoluteDir, destFile: AbsoluteFile, linkto: RelativeFile): Rope =
+  rope($relativeTo(outDir / linkto, destFile.splitFile().dir, '/'))
 
 proc genOutFile(d: PDoc): Rope =
   var
@@ -1159,15 +1159,17 @@ proc genOutFile(d: PDoc): Rope =
                  elif d.hasToc: "doc.body_toc"
                  else: "doc.body_no_toc"
   content = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, bodyname), ["title",
-      "tableofcontents", "moduledesc", "date", "time", "content", "deprecationMsg"],
+      "tableofcontents", "moduledesc", "date", "time", "content", "deprecationMsg", "theindexhref"],
       [title.rope, toc, d.modDesc, rope(getDateStr()),
-      rope(getClockStr()), code, d.modDeprecationMsg])
+      rope(getClockStr()), code, d.modDeprecationMsg, relLink(d.conf.outDir, d.destFile, theindexFname.RelativeFile)])
   if optCompileOnly notin d.conf.globalOptions:
     # XXX what is this hack doing here? 'optCompileOnly' means raw output!?
     code = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.file"), [
-        "nimdoccss", "title", "tableofcontents", "moduledesc", "date", "time",
+        "nimdoccss", "dochackjs",  "title", "tableofcontents", "moduledesc", "date", "time",
         "content", "author", "version", "analytics", "deprecationMsg"],
-        [cssHref(d.conf.outDir, d.destFile), title.rope, toc, d.modDesc, rope(getDateStr()), rope(getClockStr()),
+        [relLink(d.conf.outDir, d.destFile, nimdocOutCss.RelativeFile),
+        relLink(d.conf.outDir, d.destFile, docHackJsFname.RelativeFile),
+        title.rope, toc, d.modDesc, rope(getDateStr()), rope(getClockStr()),
         content, d.meta[metaAuthor].rope, d.meta[metaVersion].rope, d.analytics.rope, d.modDeprecationMsg])
   else:
     code = content
@@ -1318,9 +1320,12 @@ proc commandBuildIndex*(conf: ConfigRef, dir: string, outFile = RelativeFile"")
   let filename = getOutFile(conf, outFile, HtmlExt)
 
   let code = ropeFormatNamedVars(conf, getConfigVar(conf, "doc.file"), [
-      "nimdoccss", "title", "tableofcontents", "moduledesc", "date", "time",
+      "nimdoccss", "dochackjs",
+      "title", "tableofcontents", "moduledesc", "date", "time",
       "content", "author", "version", "analytics"],
-      [cssHref(conf.outDir, filename), rope"Index", nil, nil, rope(getDateStr()),
+      [relLink(conf.outDir, filename, nimdocOutCss.RelativeFile),
+      relLink(conf.outDir, filename, docHackJsFname.RelativeFile),
+      rope"Index", nil, nil, rope(getDateStr()),
       rope(getClockStr()), content, nil, nil, nil])
   # no analytics because context is not available
 

compiler/main.nim

@@ -66,20 +66,8 @@ when not defined(leanCompiler):
     compileProject(graph)
     finishDoc2Pass(graph.config.projectName)
 
-const cmdUsingHtmlDocs =
-  @["doc0",  "doc2", "doc",
-  "rst2html", "rst2tex",
-  "jsondoc0", "jsondoc2", "jsondoc", "ctags", "buildindex"]
-
-proc setOutDir(conf: ConfigRef) =
-  if conf.outDir.isEmpty:
-    conf.outDir = if optUseNimcache in conf.globalOptions: getNimcacheDir(conf)
-    elif conf.command.normalize in cmdUsingHtmlDocs: htmldocsDir.string.toAbsoluteDir
-    else: conf.projectPath
-
 proc commandCompileToC(graph: ModuleGraph) =
   let conf = graph.config
-  setOutDir(conf)
   if conf.outFile.isEmpty:
     let base = conf.projectName
     let targetName = if optGenDynLib in conf.globalOptions:
@@ -125,7 +113,6 @@ proc commandCompileToJS(graph: ModuleGraph) =
     let conf = graph.config
     conf.exc = excCpp
 
-    setOutDir(conf)
     if conf.outFile.isEmpty:
       conf.outFile = RelativeFile(conf.projectName & ".js")
 
@@ -195,8 +182,6 @@ proc mainCommand*(graph: ModuleGraph) =
   conf.searchPaths.add(conf.libpath)
   setId(100)
 
-  setOutDir(conf)
-
   proc customizeForBackend(backend: TBackend) =
     ## Sets backend specific options but don't compile to backend yet in
     ## case command doesn't require it. This must be called by all commands.
@@ -245,15 +230,28 @@ proc mainCommand*(graph: ModuleGraph) =
       defineSymbol(conf.symbols, "nimdoc")
       body
 
+  block: ## command prepass
+    var useHtmlDocs = false
+    case conf.command.normalize
+    of "r": conf.globalOptions.incl {optRun, optUseNimcache}
+    of "doc0",  "doc2", "doc", "rst2html", "rst2tex", "jsondoc0", "jsondoc2",
+      "jsondoc", "ctags", "buildindex": useHtmlDocs = true
+    else: discard
+
+    if conf.outDir.isEmpty:
+      # doc like commands can generate a lot of files (especially with --project)
+      # so by default should not end up in $PWD nor in $projectPath.
+      conf.outDir = if useHtmlDocs: getNimcacheDir(conf) / htmldocsDir
+      elif optUseNimcache in conf.globalOptions: getNimcacheDir(conf)
+      else: conf.projectPath
+
   ## process all backend commands
   case conf.command.normalize
   of "c", "cc", "compile", "compiletoc": compileToBackend(backendC) # compile means compileToC currently
   of "cpp", "compiletocpp": compileToBackend(backendCpp)
   of "objc", "compiletooc": compileToBackend(backendObjc)
   of "js", "compiletojs": compileToBackend(backendJs)
-  of "r": # different from `"run"`!
-    conf.globalOptions.incl {optRun, optUseNimcache}
-    compileToBackend(backendC)
+  of "r": compileToBackend(backendC) # different from `"run"`!
   of "run":
     when hasTinyCBackend:
       extccomp.setCC(conf, "tcc", unknownLineInfo)
@@ -266,8 +264,7 @@ proc mainCommand*(graph: ModuleGraph) =
 
   ## process all other commands
   case conf.command.normalize # synchronize with `cmdUsingHtmlDocs`
-  of "doc0":
-    docLikeCmd(): commandDoc(cache, conf)
+  of "doc0": docLikeCmd commandDoc(cache, conf)
   of "doc2", "doc":
     docLikeCmd():
       conf.setNoteDefaults(warnLockLevel, false) # issue #13218
@@ -278,7 +275,7 @@ proc mainCommand*(graph: ModuleGraph) =
         #  ## * `rand proc<#rand,Rand,range[]>`_ that returns a float
       commandDoc2(graph, false)
       if optGenIndex in conf.globalOptions and optWholeProject in conf.globalOptions:
-        commandBuildIndex(conf, conf.outDir.string)
+        commandBuildIndex(conf, $conf.outDir)
   of "rst2html":
     conf.setNoteDefaults(warnRedefinitionOfLabel, false) # similar to issue #13218
     when defined(leanCompiler):
@@ -294,14 +291,10 @@ proc mainCommand*(graph: ModuleGraph) =
       conf.cmd = cmdRst2tex
       loadConfigs(DocTexConfig, cache, conf)
       commandRst2TeX(cache, conf)
-  of "jsondoc0":
-    docLikeCmd(): commandJson(cache, conf)
-  of "jsondoc2", "jsondoc":
-    docLikeCmd(): commandDoc2(graph, true)
-  of "ctags":
-    docLikeCmd(): commandTags(cache, conf)
-  of "buildindex":
-    docLikeCmd(): commandBuildIndex(conf, conf.projectFull.string, conf.outFile)
+  of "jsondoc0": docLikeCmd commandJson(cache, conf)
+  of "jsondoc2", "jsondoc": docLikeCmd commandDoc2(graph, true)
+  of "ctags": docLikeCmd commandTags(cache, conf)
+  of "buildindex": docLikeCmd commandBuildIndex(conf, $conf.projectFull, conf.outFile)
   of "gendepend":
     conf.cmd = cmdGenDepend
     commandGenDepend(graph)

compiler/nimpaths.nim

@@ -22,6 +22,7 @@ import std/[os,strutils]
 const docCss* = "$nimr/doc/nimdoc.css"
 const docHackNim* = "$nimr/tools/dochack/dochack.nim"
 const docHackJs* = docHackNim.changeFileExt("js")
+const docHackJsFname* = docHackJs.lastPathPart
 const theindexFname* = "theindex.html"
 const nimdocOutCss* = "nimdoc.out.css"
   # `out` to make it easier to use with gitignore in user's repos

config/nimdoc.cfg

@@ -100,7 +100,7 @@ doc.body_toc = """
         <a href="lib.html">Standard library</a>
       </li>
       <li>
-        <a href="theindex.html">Index</a>
+        <a href="$theindexhref">Index</a>
       </li>
     </ul>
   </div>
@@ -143,7 +143,7 @@ doc.body_toc_group = """
         <a href="lib.html">Standard library</a>
       </li>
       <li>
-        <a href="theindex.html">Index</a>
+        <a href="$theindexhref">Index</a>
       </li>
     </ul>
   </div>
@@ -183,6 +183,9 @@ doc.body_toc_group = """
   </div>
   <div id="global-links">
     <ul class="simple">
+    <li>
+      <a href="$theindexhref">Index</a>
+    </li>
     </ul>
   </div>
   <div id="searchInputDiv">
@@ -239,7 +242,7 @@ doc.file = """<?xml version="1.0" encoding="utf-8" ?>
 <title>$title</title>
 <link rel="stylesheet" type="text/css" href="$nimdoccss">
 
-<script type="text/javascript" src="dochack.js"></script>
+<script type="text/javascript" src="$dochackjs"></script>
 
 <script type="text/javascript">
 function main() {

doc/docgen.rst

@@ -30,12 +30,14 @@ Generate HTML documentation for a whole project:
 
 ::
   # delete any htmldocs/*.idx file before starting
-  nim doc --project --index:on --git.url:<url> --git.commit:<tag> <main_filename>.nim
-  # this will generated docs under `htmldocs` by default and an index under
-  # `htmldocs/theindex.html`. See also `--docroot` to specify a relative root.
+  nim doc --project --index:on --git.url:<url> --git.commit:<tag> --outdir:htmldocs <main_filename>.nim
+  # this will generate html files, a theindex.html index, css and js under `htmldocs`
+  # See also `--docroot` to specify a relative root.
   # to get search (dochacks.js) to work locally, you need a server otherwise
   # CORS will prevent opening file:// urls; this works:
   python3 -m http.server 7029 --directory htmldocs
+  # When --outdir is omitted is defaults to $nimcache/htmldocs. You can also do:
+  `nim doc -r --project --index main` to open in a browser directyl.
 
 
 Documentation Comments

tests/misc/trunner.nim

@@ -68,15 +68,15 @@ else: # don't run twice the same test
     # regression tests for issues and PRS: #14376 #13223 #6583 ##13647
     let file = testsDir / "nimdoc/sub/mmain.nim"
     let mainFname = "mmain.html"
-    let htmldocsDir1 = nimcache /  "htmldocs" # implicit one given we're using `workingDir = nimcache`
+    let htmldocsDir1 = nimcache /  "htmldocs" # implicit one
     let htmldocsDir2 = nimcache / "htmldocs2" # explicit one
     let docroot = testsDir / "nimdoc"
     let options = ["", "--docroot", "--project:off", fmt"--project:off --outDir:{htmldocsDir2}", fmt"--project:off --docroot:{docroot}"]
     for i in 0..<options.len:
       let htmldocsDir = if i == 3: htmldocsDir2 else: htmldocsDir1
       var cmd = fmt"{nim} doc --project --index:on --listFullPaths --hint:successX:on --nimcache:{nimcache} {options[i]} {file}"
       removeDir(htmldocsDir)
-      let (outp, exitCode) = execCmdEx(cmd, workingDir = nimcache)
+      let (outp, exitCode) = execCmdEx(cmd)
       check exitCode == 0
       proc nativeToUnixPathWorkaround(a: string): string =
         # xxx pending https://github.com/nim-lang/Nim/pull/13265 `nativeToUnixPath`
@@ -183,14 +183,10 @@ sub/mmain.idx""", $(i, cmd)
       let cmd = fmt"""{nim} doc -b:{backend} --nimcache:{nimcache} -d:m13129Foo1 "--doccmd:-d:m13129Foo2 --hints:off" --usenimcache --hints:off {file}"""
       check execCmdEx(cmd) == (&"ok1:{backend}\nok2: backend: {backend}\n", 0)
     # checks that --usenimcache works with `nim doc`
-    check fileExists(nimcache / "m13129.html")
+    check fileExists(nimcache / "htmldocs/m13129.html")
 
     block: # mak sure --backend works with `nim r`
       let cmd = fmt"{nim} r --backend:{mode} --hints:off --nimcache:{nimcache} {file}"
-      echo cmd
-      let ret = execCmdEx(cmd)
-      echo ret[0]
-      echo ret[1]
       check execCmdEx(cmd) == ("ok3\n", 0)
 
   block: # further issues with `--backend`
@@ -207,4 +203,4 @@ sub/mmain.idx""", $(i, cmd)
     # issue #14314
     let file = testsDir / "misc/mimportc.nim"
     let cmd = fmt"{nim} r -b:cpp --hints:off --nimcache:{nimcache} --warningAsError:ProveInit {file}"
-    check execCmdEx(cmd) == ("witness\n", 0)
+    check execCmdEx(cmd) == ("witness\n", 0)

tests/nimdoc/m13129.nim

@@ -17,11 +17,9 @@ proc main*() =
     doAssert defined(m13129Foo2)
     doAssert not defined(nimdoc)
     echo "ok2: backend: " & querySetting(backend)
-    # echo defined(c), defined(js), 
 
 import std/compilesettings
 when defined nimdoc:
-  # import std/compilesettings
   static:
     doAssert defined(m13129Foo1)
     doAssert not defined(m13129Foo2)