Support both github and sphinx links

[mgsloan]

There have been quite a few PRs changing links in the docs - #1420 #1444 #1446 #1449 #1505. We should fix things so that the links work in the github view of the docs, so more time isn't spent on changing them. I see two options:

• Automatically munge .md to be .html when generating the docs. This is the option I prefer
• Replace all the relative links with absolute links to docs.haskellstack.org. This is a bad solution, because it doesn't work well for hosting multiple versions of the docs / following links locally. Also, the site structure may change.

[borsboom]

If anyone knows Sphinx and/or readthedocs well, maybe they can suggest a way to do the munging. I spent a little while when I first put stuff on readthedocs trying to find an obvious way. Using MkDocs instead of Sphinx does change the URLs, but unfortunately introduces a bunch of worse problems. The other way around this is to have readthedocs redirect the from *.md to *.html, and I tried that, but then I ran into readthedocs/readthedocs.org#1826.

[mgsloan]

Yes, that seems like a reasonable solution, toobad rtfd is broken :/. Here's my take on the order of more "correct" solutions to less "correct" solutions:

1. Add / wait for support for URL munging to sphinx
2. Add / wait for redirects to be fixed in rtfd
3. Preprocess the markdown files, munging the links

On one hand, 1 and 2 are more "correct" in that they address some systemic issue. (3) could be implemented by parsing, munging, reserializing the markdown, but I'm not sure if we have a parser / serializer that matches this markdown flavour. I'm thinking that just preprocessing it with some regexes would do the trick. Hacky, certainly, but it means we could fix the issue nowish instead of waiting on (1) or (2)

[borsboom]

(3) is hard because we don't have control of what is run before/after the documentation build (since RTFD pulls the repo itself). Best bet would be writing our own builder, but not at all clear about how exactly to go about that (wish they provided an example).

[mgsloan]

Another option, and a rather terrible one, would be to check in the munged md files..

[lethjakman]

This may be a dumb question, but shouldn't mkdocs handle this for you? I'm reading the documentation and they internally reference the .md files and it parses to .html: https://mkdocs.readthedocs.org/en/0.9/user-guide/writing-your-docs/#linking-documents.

[borsboom]

I've switched the doc generation over to MkDocs (readthedocs.org fixed the problems) and rewritten all the links back to .md extensions.