Generating links with `link text <./path/to/doc#anchor>`__ does not work for html.
It produces a link to `./path/to/doc#anchor` instead of `./path/to/doc.html#anchor`.
It would be tempting to add `.html` before `#` but would likely cause some more issues
when generating the documentation as pdf or epub.
References on the other hand will work regardless of the output format.
