Support both github and sphinx links #1506

Closed
mgsloan opened this Issue Dec 12, 2015 · 6 comments

Projects

None yet

3 participants

@mgsloan
Collaborator
mgsloan commented Dec 12, 2015

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.
@mgsloan mgsloan added this to the P2: Should milestone Dec 12, 2015
@borsboom
Contributor

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.

@mgsloan
Collaborator
mgsloan commented Dec 17, 2015

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
Contributor

(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
Collaborator
mgsloan commented Dec 20, 2015

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.

This was referenced Jan 29, 2016
@borsboom borsboom added a commit that referenced this issue Feb 19, 2016
@borsboom borsboom 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.
WIP

WIP

WIP

WIP
1448a41
@borsboom
Contributor

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

@borsboom borsboom closed this Feb 19, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment