Page MenuHomePhabricator

[docs] Fix local docs build
AbandonedPublic

Authored by jhenderson on Jun 12 2019, 8:28 AM.

Details

Summary

I have no idea why the build bots are not failing for this but after rL363100 I get build failures when trying to build the docs with the warning (promoted to an error) of "None: any reference target not found" (there may have been more context, but I don't have that any more). This change, inspired by the working links in llvm-addr2line.md, fixes the issue.

Diff Detail

Repository
rL LLVM

Event Timeline

jhenderson created this revision.Jun 12 2019, 8:28 AM
Herald added a project: Restricted Project. · View Herald Transcript

I intentionally added .html because I noticed the link on llvm.org is broken: http://llvm.org/docs/CommandGuide/llvm-addr2line.html links to http://llvm.org/docs/CommandGuide/llvm-symbolizer, which does not exist (http://llvm.org/docs/CommandGuide/llvm-symbolizer.html does).

Hmm... Interesting. When I build this locally, the links are correct (linking to llvm-symbolizer.html etc as expected). What version of sphinx-build are you using? And what are the bots using, because I'm guessing that might be the difference.

Looks like I'm on 1.7.5, from last year (http://www.sphinx-doc.org/en/master/changes.html#release-1-7-5-released-may-29-2018). Not sure how to check the bot version.

FWIW, I think this patch is the preferred way to go once we can figure out why it's not working.

FWIW, the full error text I got from the build was:
C:\llvm\llvm\docs\CommandGuide\llvm-objcopy.md:16:None:any reference target not found: llvm-strip.html

pip tells me I have version 1.8.5 of Sphinx installed, and version 0.5.0 of recommonmark. Unfortunately, the documentation is not really helpful on this topic at all. This github comment seems to suggest that it is supported: https://github.com/rtfd/recommonmark/issues/8#issuecomment-279661887, but I wasn't able to understand the conclusion at all.

Could you try running those versions if you get a moment and see if you see the same issue? I wonder if it's a behaviour change somewhere along the lines (though don't ask me what the error message is about - I tried searching online and failed to find anything relevant).

I just started setting up a new Ubuntu 18.04 machine with the intent of migrating away from my old 14.04 installation, and I see the exact same error, with the same versions, so it's not a Windows problem.

I downgraded sphinx and recommonmark to 1.7.5 and 0.4.0 respectively. This allowed the build to complete, but the addr2line link broke, like on the build bots. I then upgraded only recommonmark to 0.5.0, and the build broke (but the link worked). Finally, I downgraded recommonmark back to 0.4.0, and upgrdade sphinx to 1.8.5 and the link is broken, but the build passes.

I'm now certain that it's a version difference in recommonmark, and I think we should update the build bots, and land this patch at the same time. I'll try contacting the build bot maintainers.

I replied to your llvm-dev thread. I think we should apply something like D63292, upgrade the buildbots, and then apply this change when reverting D63292.

jhenderson abandoned this revision.Mon, Jun 24, 2:50 AM

There seems to be a general consensus to change these docs to RST (see also the discussion in D63292 and on the mailing list). As such, I'm abandoning this revision. I'll make changes in the coming days to switch things over.