misc docgen (not documentation)

[timotheecour]

• top-level runnableExamples should work; right now they're avoided (in favor of code-block::nim) bc AFAIR they're not rendered properly

[timotheecour]

• --lib not honored for nim doc runnableExamples, eg:

nim doc --lib:lib $nim_prs_D/lib/system/setops.nim
/Users/timothee/.cache/nim/setops_d/runnableExamples/setops_examples.nim(1, 1) template/generic instantiation from here
/Users/timothee/.cache/nim/setops_d/runnableExamples/setops_examples1.nim(6, 1) template/generic instantiation from here
/Users/timothee/.cache/nim/setops_d/runnableExamples/setops_examples1.nim(8, 2) template/generic instantiation from here
/Users/timothee/git_clone/nim/Nim_prs/lib/system/setops.nim(102, 15) Error: ambiguous call; both setops.incl(x: var set[T], y: set[T]) [declared in /Users/timothee/git_clone/nim/Nim_prs/lib/system/setops.nim(11, 10)] and system.incl(x: var set[T], y: set[T]) [declared in /Users/timothee/git_clone/nim/Nim_devel/lib/system/setops.nim(11, 10)] match for: (set[char], set[char])
    if val: incl(s, y)
                ^

[timotheecour]

• we need: nim doc --target:js foo
  eg use case: print docs for js functions in files with when defined(js): ...

and then show the docs for specific targets

A: --backend:js

[timotheecour]

• nim doc lib/system/dollars.nim doesn't print any SuccessX unlike nim doc lib/pure/json.nim

unlike:

nim doc lib/pure/json.nim
Hint: 51042 LOC; 0.857 sec; 62.031MiB peakmem; Debug build; proj: /Users/timothee/.cache/nim/json_d/runnableExamples/json_examples.nim; out: /Users/timothee/.cache/nim/json_d/runnableExamples/json_examples [SuccessX]
Hint: operation successful: runnableExamples: /Users/timothee/.cache/nim/json_d/runnableExamples/json_examples.nim [Success]
Hint: 51314 LOC; 1.892 sec; 62.102MiB peakmem; Debug build; proj: /Users/timothee/git_clone/nim/Nim_devel/lib/pure/json.nim; out: /Users/timothee/git_clone/nim/Nim_devel/json.html [SuccessX]

Edited:
Now it has:

Hint: 22859 lines; 1.280s; 20.625MiB peakmem; Debug build; proj: D:\QQPCmgr\Desktop\Nim\lib\system\dollars.nim; out: D:\QQPCmgr\Desktop\Nim\lib\system\htmldocs\dollars.html [SuccessX]

[timotheecour]

imports not listed unless from same project

[timotheecour]

reopen doc2 outputs in current work dir · Issue #6583 · nim-lang/Nim

see nim-lang#6583 (comment)

[timotheecour]

https://github.com/nim-lang/Nim/issues/14313#issuecomment-630187073 manual.rst => manual.nim

[timotheecour]

TODO's from fix #6583, fix #14376, index+search now generated for all projects, many bug fixes with nim doc by timotheecour · Pull Request #14324 · nim-lang/Nim

• nim doc --project -o:sub/bar.html main outputs sub/bar.html/main.html ; it's a preexisting odd/buggy behavior from the times outdir didn't exist
  => nim doc --project --out:foo/bar.html doesn't work; creates foo/bar.html/ dir instead of a file nim-lang/Nim#14508
• dochacks.nim hardcodes request.open("GET", "theindex.html", false); which is incorrect (eg if using custom theindex.html, or if subdirs are involved); since this never worked before in those cases it can be fixed in a future PR (but at least now dochacks works for user projects if no subdirs and using the exact name theindex.html)
• nim doc --index generates incorrect module href, fooled by doc comments nim-lang/Nim#14434 as well
• the ad-hoc idx files should be replaced simply by json
• eventually I hope we can replace all those hand generated html by karax, which would be: less buggy, faster, easier to read/write
• Uncaught TypeError: Cannot read property 'addEventListener' of null

[timotheecour]

instead of asking user to delete htmldocs contents in https://nim-lang.github.io/Nim/docgen.html, we can simply regenerate theindex more smartly to only track what is needed ; this will fix a bug w stale htmldocs contents

[timotheecour]

• proc declarations should generate clickable links when possible for default values
  this would avoid having to specify it in doc comment eg: (default: defaultInitialSize).
  

https://github.com/nim-lang/Nim/pull/16589/files

[timotheecour]

• see nice looking rust docs: 0042-regexps - The Rust RFC Book