Fix failing build by removing broken mirror in README.rst

Parser (and other) documentation fixes

Previously the parser documentation did not include warnings and
exceptions. This rearranges things to cleanly separate out functions,
classes and exceptions / warnings, and adds the warnings to the
documentation.

Periodic update of all links that point to redirects or http targets
when an https target is available.

Fix custom repr for ParserError

This was originally dead code, because an indentation error had `__repr__`
defined after the `return` statement in `__str__`. The definition of the
`__repr__` is also changed to be more in line with the conception of a
repr as "what you would have to evalue to get this object".

Even though this is not guaranteed behavior, this commit also adds a
regression test to avoid simple errors like this in the future.