rst: rst2html and doc now have clickable anchors for each paragraph/list element

[timotheecour]

/cc @a-mr since you're our RST expert ;-)

fixes most of nim-lang/RFCs#117, plus a few other related improvements.
We can now point to any paragraph/list element in docs (rst or nim) and use it to share links. Ones in between stable anchor names (derived from a title or an anchor name) are considered non-stable and start with - to denote this. They're unstable in the sense that if a new paragraph/list element is added in the interval anchoredName .. generatedAnchoredName, the numbering may be off. This is expected and allows working with the common case of paragraphs/list elements that don't have an anchor name, yet still allow sharing links.

there are 3 kinds of anchors:

• ones from title (eg Best practices below): anchor name is derived from title
• ones from explicit anchor (eg .. _noimplicitbool below): anchor name is explicitly provided and shouldn't change. Likewise for [display](link) markdown syntax
• ones in between (eg foo, bar): anchor name is derived from the last seen anchor name, plus an incrementing counter.

Best practices
==============

.. _noimplicitbool:
Take advantage of no implicit bool conversion

1. foo
2. bar

design notes

• I'm ignoring hierarchy when deriving intermediate anchor names, it's the simplest and produces good results, try it, eg: nim rst2html -r doc/contributing.rst or nim rst2html -r --doccmd:skip doc/manual.rst

TODO before merging

• CI failures
  only tests/stdlib/trstgen.nim fails, I'll fix it once the formatting in this PR is accepted to avoid back and forth on editing the tests

• $nimb r nimdoc/rsttester.nim fails, I'll fix it once the formatting in this PR is accepted to avoid back and forth on editing the tests

• see how this shows anchors on mouse over (hover) https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html (eg when hovering on right of Links to External Web Pages)

future work

• (pre-existing) subsection titles shouldn't depend on parent name, it's a false good idea IMO; if parent name changes, it invalidates more links. The rare case of duplicates titles should be handled instead differently (eg error/warning):
  https://nim-lang.github.io/Nim/manual.html#distinct-type-avoiding-sql-injection-attacks
  =>
  https://nim-lang.github.io/Nim/manual.html#avoiding-sql-injection-attacks
• (pre-existing) rstnodeToRefnameAux shouldn't translate - as minus, this is anchor name is bad:
  https://nim-lang.github.io/Nim/manual.html#types-preminusdefined-integer-types
• generate anchors as well for code blocks, runnableExamples, and infer anchor name from symbols in nim doc in above logic
• address simpler doc links: getFilePermissions <#getFilePermissions,string>_ => $getFilePermissions RFCs#125

[Araq]

Why is this needed? It's supposed to be a strict tree structure or at least an acyclic graph.

[timotheecour]

it's needed because I'm processing the whole tree/DAG upon 1st call to renderRstToOut, and because renderRstToOut is reentrant. This sentinel avoids needs for a separate flag.
Without this logic, you can see it doesn't work:
nim rst2html -r doc/contributing.rst
the anchor next to separate test files would be #-ROOT-2 instead of #-writing-tests-3

[a-mr]

The idea is great.

The current style is too visually disturbing.

I'd like to put these marks outline: either to the left side margin of the text (where yellow dots are on the picture) or to the right margin (green dots):

Unfortunately I don't know how to do it in HTML. But I think I've seen something like that somewhere.

[a-mr]

Is this additional field really needed? When anchor is already defined you just use it; when it's not — you generate it. Anchor is always unique for any node.

[timotheecour]

removed anchorGen (and reuse anchor), but added anchorKind which determines the kind of anchor (needed for book-keeping, among other things to make this work:

if n.anchorKind == raDefault: computeAnchorGen(n)

and knowing the kind of the anchor can be useful for other purposes.

[stale]

This pull request has been automatically marked as stale because it has not had recent activity. If you think it is still a valid PR, please rebase it on the latest devel; otherwise it will be closed. Thank you for your contributions.