[WIP] [doc] miscellaneous issues

[timotheecour]

major

• templates expand doc comments as documentation of other procedures · Issue #9432 · nim-lang/Nim
• need a way to expose NimNode comments for user macros for tooling expose API to get NimNode doc comments, for tooling #8516
• [parser] top-level comment attached to wrong node, makes nim doc buggy [parser] top-level comment attached to wrong node, makes nim doc buggy #8929
• [regression] nim doc foo/bar.nim should generate by default in htmldocs instead of foo/bar.html (makes it hard to gitignore otherwise) [WONTFIX] [regression] nim doc foo/bar.nim should generate by default in htmldocs instead of foo/bar.html (makes it hard to gitignore otherwise) #8873
• theindex.html should reference pragma definitions, eg:
  {.pragma: benign, gcsafe, locks: 0.} => pragma: foo (eg: benign) should end up in index / documentation #10123
• theindex.html should reference exported symbols in compiler (eg TGlobalOption ; having it in theindex.html makes it much easier to develop Nim compiler)
• Atheindexjson: [search] --json2 doesn' work with ./koch web (needed to get theindex.json for tooling) exporting documentation to json does not work properly #8495
• already-clicked links in generated doc are undistinguishable from normal text already-clicked links in generated doc are undistinguishable from normal text #7452
• [regression] [nim doc] code from other module ends up in html rendered from nim doc foo.nim code from other module ends up in html rendered from nim doc foo.nim #8872
• [feature] access docs for devel branch · Issue #98 · nim-lang/website
• [regression] nim doc --project foo/bar.nim generates under htmldocs/absolute/pathto/foo/bar.nim instead of htmldocs/foo/bar.nim [regression] nim doc --project foo/bar.nim generates under htmldocs/absolute/pathto/foo/bar.nim instead of htmldocs/foo/bar.nim #8874
• [doc] nim doc --project creates wrong href links, eg: test3.html instead of util/test3.html [doc] nim doc --project creates wrong href links, eg: test3.html instead of util/test3.html #8736
• nim doc2 --project -o:doc/ cannot find files in subdirectories nim doc2 --project -o:doc/ cannot find files in subdirectories #8218

minor

• times.html (etc) should show its (relative) source location, eg lib/pure/strutils.nim; at least via top-level source/edit links
• update the documention generator's documentation (EDIT)
• get rid of all references of doc0 doc2 and just use doc (but keeping doc0, doc2 as undocumented cmds for backward compatibility) ( bad example in https://nim-lang.org/docs/docgen.html #8215 (comment) )
• nim doc2 ignores --docSeeSrcUrl parameter nim doc2 ignores --docSeeSrcUrl parameter #6071 (workaround available)
• new nim doc flag: --git.commit_current to pass in git rev-parse --abbrev-ref HEAD as value for git.commit which is a good default when developping: we want to see docs for branch we're currently on (fits along --git.devel, --git.url, --git.commit)
• [minor] nim doc renders generic badly (extra ;): template default[T; ](t: typedesc[T]): T [minor] nim doc renders generic badly (extra ;): template default[T; ](t: typedesc[T]): T + bad formatting #8488
• tags are not change-safe, eg: https://nim-lang.org/docs/strformat.html#17 is numeric, https://nim-lang.org/docs/strformat.html#fmt-vs is auto-named.
  neither is good: numeric ones are the worst, they change when there are inserts; and auto-named ones cause breakage when title changes (which happened multiple times) (especially bad when ppl bookmark these and we have no control over their bookmarks). A better fix: use auto-names, and when title changes, use explicitly named anchor using old name (unless we want the old anchor to stop working which should be uncommon); this could be enforced by tooling.
• fix issue bad example in https://nim-lang.org/docs/docgen.html #8215 remove reference to old doc command which was deprecated fix issue #8215 remove reference to old doc command which was deprecated #8418

scratch

[Make pragmas look clickable in docs by Quelklef · Pull Request #8176 · nim-lang/Nim](https://github.com/nim-lang/Nim/pull/8176)
./compiler/docgen.nim
Better doc search (#8260)

- [ ] check whether this is this still the case: https://github.com/nim-lang/Nim/pull/8182#issuecomment-402138537
When deprecating you need to update the doc comment:

## ...
##
## **Deprecated since v0.19.0:** use toSeq instead
Please be sure to add an empty ## line so that this is formatted well in the doc gen.

[Araq]

Keep in mind to also update the documention generator's documentation.

[timotheecour]

will close this issue but keep updating it