links in INSTALL don't work on both github and readthedocs

[warner]

Currently, docs/INSTALL.rst uses `about.rst`_ and .. _about.rst: about.rst to generate a hyperlink to docs/about.rst (and the same for windows.rst and OS-X.rst). This works for github's RST renderer, but yields broken links on ​Read The Docs.

[02362ae] changed this from :doc:`about`, which worked on Read The Docs but not on github.

We need a syntax that works on both renderers.

I'd like to get this fixed for 1.12, but I'm willing to drop it if nobody has a bright idea about how to make it work in both places.

[warner]

For reference, I think ​https://github.com/github/markup might define how github does rendering.

I haven't yet found a syntax that works in both places, because ReadTheDocs (which is really just Sphinx-as-a-service) generates/serves .html files, whereas GitHub knows the files by their original .rst names. Sphinx knows which files it has translated, so a :doc: link will point to the post-translation name (.html), but GitHub has no such translation.

My inclination at this point is to use ReadTheDocs syntax, and add a docs/README that says "if you're reading this on github, please follow this link to readthedocs instead, where the hyperlinks will be rendered properly". And maybe add a single extra link or two from just the INSTALL doc (i.e. provide both syntaxes) if we think it's likely that many people will end up reading it there.

[warner]

Github's .rst renderer is using the same docutils that Sphinx uses, but the :doc: handler lives in Sphinx, not docutils (​https://github.com/sphinx-doc/sphinx/blob/1.5/sphinx/roles.py#L327). So Github won't be able to handle any of those special links.

[Brian Warner <warner@…>]

In 91047bf/trunk:

docs: clean up .rst and references

This uses Read-The-Docs (sphinx/docutils) references exclusively, but adds a
README.md for GitHub? viewers to remind them that the links there won't
work (closes ticket:2835).

It also fixes all the dangling references and other Sphinx warnings.

The "Preparation" section of docs/magic-folder-howto.rst was removed, since
this feature has since been merged to trunk.