Fix duplicate implicit references with the same id

[wouterj]

This fixes a common bug in the docs (it has been reported multiple times over the past couple weeks).

If two or more titles on the same page have the same name, the references to the sections is wrong (as the ID is duplicate, you can never link to the second section).

Sphinx/docutils solve this by replacing any duplicate internal references with id1, id2, etc. I suggest making things a bit nicer by adding -1, -2, ... to the actual reference ID instead.

For reference, docutils actually manages references using a node visitor pattern. We've discussed adding something like this before (#145), but with the ongoing development on PHPdocumentor's side, I'm trying to keep the changes to this library to a minimal.

[wouterj]

Converting to draft: I realized some parts of this library still rely on simply calling Environment::slugify() to get a reference to a title.

[linawolf]

@wouterj might this be fixed by #232?