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:
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 rtfd/readthedocs.org#1826.
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:
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)
(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).
Another option, and a rather terrible one, would be to check in the munged md files..
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.
Switch to MkDocs for doc generation
This allows us to use '.md' extensions in links (#1506), and the
formatting is a bit nicer and closer to how GitHub renders.
I've switched the doc generation over to MkDocs (readthedocs.org fixed the problems) and rewritten all the links back to .md extensions.