simpler doc links: `getFilePermissions <#getFilePermissions,string>`_ => $`getFilePermissions`

[timotheecour]

this PR nim-lang/Nim#10492 adds a lot of great documentation how ever it also adds a lot of things like:

`getFilePermissions <#getFilePermissions,string>`_

which are required today by docgen to produce valid links.
This is not DRY for 2 reasons:

• the name is consistently repeated twice
• the args are mentioned which is a different kind of DRY violation (args mention in source code as well as in that doc link)

other drawbacks:

• this makes for less readable docs when browsing source code

• it increases risk of links becoming out of sync when proc signature changes (eg an extra (optional) param is later added, which can often happen)

• discourages using proper doc links as it adds a barrier to "get it right" (which explains why so few procs have these links)

• EDIT: doc links are order-dependent:

proc fn*[T: SomeFloat](a: T)=discard
proc fn*[T: SomeInteger](a: T)=discard

generates:

fn,T
fn,T_2

proposal

• add a DRY and easy to remember syntax to refer to a symbol (see below for concrete syntax)
• let docgen resolve it to an actual doc link exactly as it would if user typed getFilePermissions <#getFilePermissions,string>_ in full
• the only problem is when symbol is overloaded; there are 2 approaches
  • make docgen issue an ambiguity error and require full syntax getFilePermissions <#getFilePermissions,string>_ or something a bit DRY-er getFilePermissions <string>_
  • make docgen resolve to the 1st symbol it finds; shouldn't be a big deal; overloads are generally placed next to each other and oftentimes only 1 is documented anyway;

in any case this is a practicaly tradeoff: we improve situation for the 95% case and make the 5% case well, as bad as it already is today

concrete syntax for the proposal

open to suggestions;
maybe:

see also $`getFilePermissions` which is related # docgen will resolve to same as `getFilePermissions <#getFilePermissions,string>`_
see also $`strutils.foo` which is related # docgen will resolve to same as `strutils.foo <#strutils.foo,string,int>`_ # ie, can use modules in other symbols

benefits:

• would fix Fix broken links in docs Nim#16337
• broken links would give CT errors when running nim doc
• links would be easier to read/write/edit
• each link would give rise to an entry in the index
• links wouldn't break when you change a proc to a func or add optional params
• there are easy ways to handle overloaded procs in the same module, I can describe what I have in mind

[ringabout]

Yeah, I agree.
Original doc links way makes proc + nosideEffect => func a bit annoying.

[a-mr]

RST has the mechanism of custom roles for "interpreted text" (between ``).

So proper RST-style syntax would be something like:

:nim:`proc getFilePermissions`
:nim:proc:`getFilePermissions`

We can parse the text inside `` to generate proper link so we can get close to actual definition of the proc:

:nim:`proc getFilePermissions(string)`
:nim:proc:`getFilePermissions(string)`

Probably we can also study how it's done in sphinx

cc @konsumlamm