Improve documentation

Change some sentences that were not clear enough, fix some markup,
correct some spelling mistakes and, most importantly, do not hardcode
the version in the ReST files but use Sphinx's substitution feature.
Since the version was also in the download URL and since no substitution
is allowed there we had to write an extension to do that. We also took
this opportunity to add a new role to more easily reference GitHub
issues. It's largely inspired by the extlinks extension (since it
basically does the same thing).