stable doc unique ids , index, lightweight symbol references, indicate where a proc is tested; idx

[timotheecour]

use case

allows stable references for any link (eg runnableExample, symbol, doc paragraph, referencing doc from a compiler error msg etc)
eg: for this nim-lang#14340 (comment)

No stack traceback available
To create a stacktrace, rerun compilation with ./koch temp r <file>, see https://nim-lang.github.io/Nim/intern.html#bootstrapping-the-compiler

note

would replace those links:

  ## * `& proc <#&,seq[T][T],seq[T][T]>`_

which are hard to type/read and get stale if a proc gets updated (eg new optional param)

would also replace anchors-based-on-title which often get stale after title changes

eg

datestring2
D20200517T232720
or use oids
use unique prefix that gets correctly interpreted/highlighted/indexed by docgen + compiler

implementation

expose: setIndexTerm ?
recognize special links eg: foo:here

related

proc takeImplicitAddr(c: PContext, n: PNode; isLent: bool): PNode =
  # See RFC #7373, calls returning 'var T' are assumed to
  # return a view into the first argument (if there is one):
  let root = exprRoot(n)
  if root != nil and root.owner == c.p.owner:
    if root.kind in {skLet, skVar, skTemp} and sfGlobal notin root.flags:
      localError(c.config, n.info, "'$1' escapes its stack frame; context: '$2'; see $3/var_t_return.html" % [
        root.name.s, renderTree(n, {renderNoComments}), explanationsBaseUrl])

indicate where a proc is tested

block: ## `test:isRelativeTo`
  doAssert isRelativeTo("/foo", "/")

ligthweight references

• nim doc can give a warning when baz is ambiguous (defined in multiple modules), or not defined at all
• no warning when it's just an overload but defined in a single module (frequent case)
• hyperlink can resolve to just the 1st found overload, or to entry in the index, or to populating dochack search using clickable selections

proc fun* =
  ## see `mod.bar`, see `baz`

ligthweight definitions

definitions can happen in any doc comment, eg:

runnableExamples: ## `def:importcExample`
	# code showing how to use {.importc.}

example

lent isn't documented in manual and searching for lent in index returns nothing
it turns out it's document here https://nim-lang.github.io/Nim/destructors.html
=> but it should be in index, and it should be searchable by lent

see also: idx feature in docgen

• This is similar to super:idx: in ordinary OO languages.
  but it doesn't work as well, it only points to here from index but doesn't implement ODR

• note: idx terms should be highlighted but they're not:

> If b.len is not exactly the number of elements that are referred to by x, a splice is performed:

• it shouldn't show Misc but smthg more informative
• should be searchable wo regex, eg shown in index as -case: (note the prefix -)
• should be searchable in search box
• doesn't work if inside RST file eg

doc/manual.rst:6144:21:compile a Nim `case`:idx: statement. Syntactically it has to be used as a

• shd create a tag eg https://nim-lang.github.io/Nim/system.html#splice_1

links

nim-lang#9477