Page MenuHomePhabricator

[docs] Workaround old recommonmark version on buildbots
AbandonedPublic

Authored by rupprecht on Jun 13 2019, 11:44 AM.

Details

Summary

recommonmark 0.4.0 doesn't understand md -> rst links (and so adding .html is required), but recommonmark 0.5.0 emits a warning (which we treat as errors) when hitting this.

Work around this by temporarily using regular, non-markdown links.

Revert this after upgrading the buildbots to recommonmark 0.5.0, and then fix the links to not explicitly include the .html in these files (except llvm-addr2line, which is already broken on llvm.org).

Event Timeline

rupprecht created this revision.Jun 13 2019, 11:44 AM
Herald added a project: Restricted Project. · View Herald Transcript

html can be embedded in markdown? That was unexpected and sounds good. Does this work when generating man pages though instead of html?

html can be embedded in markdown? That was unexpected and sounds good. Does this work when generating man pages though instead of html?

If it doesn't solve the problem (because of man pages), maybe we're better off cutting our losses and changing the .md files to .rst, since the feedback on the mailing list seems to be that we can't upgrade the version of recommonmark.

html can be embedded in markdown? That was unexpected and sounds good. Does this work when generating man pages though instead of html?

If it doesn't solve the problem (because of man pages), maybe we're better off cutting our losses and changing the .md files to .rst, since the feedback on the mailing list seems to be that we can't upgrade the version of recommonmark.

*very* weak +1 here, it seems weird to use non-native .MD when sphinx is based on .RST.

rupprecht abandoned this revision.Jun 21 2019, 4:41 PM

Switching these docs to rst seems (unfortunately) better, abandoning this attempt.

Switching these docs to rst seems (unfortunately) better, abandoning this attempt.

Okay. I'll go ahead and fix things up over the next few days. I'm planning on expanding the majority of the docs anyway, so it's a good opportunity to switch over then.