[llvm-commits] Unbork Sphinx docs build

[Sean Silva]

Ping.

On Tue, Aug 21, 2012 at 12:04 AM, Sean Silva <silvas at purdue.edu> wrote:
> Good catch, it looks like the sphinx option I used to copy them is
> putting the HTML files under _static/ which breaks the links. I must
> have had stale HTML files sitting in _build/html (I thought I did a
> `make clean` beforehand...I guess not).
>
> I've attached a new patch that remedies the situation by using a hack
> in the Makefile and just `cp`'ing the HTML files into the build
> directory.
>
> I couldn't make the corresponding change to `make.bat` due to being
> unfamiliar with .bat files. Michael, do you know enough .bat-fu to
> fixup `make.bat`? I don't think that `make.bat` is a patch-blocker
> anyway, since typically a local Sphinx build is done while writing
> documentation, which should be all in Sphinx now anyway (and plus, you
> can directly open the .html files in the browser if you really need to
> (like, say, the as-yet unconverted LangRef, which gets updates from
> time-to-time)). Well, unless the docs for llvm.org are generated on
> Windows, which I doubt.
>
> So basically copy `llvm-theme/` into a new directory _themes/ (as I
> described in the OP) and apply the new patch `unbork-sphinx.patch`.
> Does that work for you Michael? I double checked and everything is
> working here. Locally, tutorial/ is not showing nicely (it just shows
> the "file browser" of the local directory) since there isn't a
> webserver running to automatically serve index.html; I verified that
> this also happens on master, so it is not a regression.
>
> --Sean Silva
>
> On Mon, Aug 20, 2012 at 7:01 PM, Michael Spencer <bigcheesegs at gmail.com> wrote:
>> On Sun, Aug 19, 2012 at 3:12 PM, Sean Silva <silvas at purdue.edu> wrote:
>>> Working on LLVM's Sphinx documentation, I've been noticing that it is
>>> abysmally slow to build. In particular, despite Sphinx having
>>> capabilities of doing incremental builds, it is rebuilding all of the
>>> files every time. I was able to track down the culprit and fix the
>>> problem.
>>>
>>> The problem is that the LLVM Sphinx theme (llvm-theme/) is in the root
>>> Sphinx directory. This causes Sphinx add the root docs/ directory to
>>> an internal path list which is used to determine whether any of the
>>> templates are out of date. When building one of the .rst files,
>>> Sphinx's logic considers it out of date if *any* of the templates are
>>> newer than it. In order to check if any of the templates are newer
>>> than it, it takes the most recent modification time of not just the
>>> template files, but any files with a .html extension recursively
>>> contained in the above-mentioned path. So basically, since _build is
>>> under the root sphinx directory, the generated HTML files in
>>> _build/html were being considered.
>>>
>>> The fix is simple enough, just move llvm-theme into a new _themes/
>>> directory, and update `html_theme_path` to be "_themes" instead of
>>> ".". Unfortunately, this has a bit of fallout, since apparently the
>>> way we are currently handling the legacy HTML-formatted docs with
>>> `html_additional_pages`, which ends up treating them like templates,
>>> which causes Sphinx to error when handling _themes/llvm-theme since
>>> the paths it is being fed are relative to the root Sphinx directory.
>>> The fix for this is to add the root directory to the
>>> `html_static_path` variable, which causes Sphinx to copy the legacy
>>> HTML-formatted documentation pages into the build directory through a
>>> different and better mechanism that just copies the files, rather than
>>> running them through the slow Python templating mechanism that Sphinx
>>> uses (which is a noop anyway since those HTML files don't contain
>>> jinja tags).
>>>
>>> tl;dr
>>> How to unbork it:
>>>
>>> Because the llvm-theme directory contains some binary files, it is not
>>> very patch friendly, so please just do
>>>
>>> cd docs/
>>> mkdir _themes
>>> git mv llvm-theme _themes
>>>
>>> and then apply the patch 01-conf.py.patch
>>>
>>> --Sean Silva
>>
>> This breaks the link to the tutorial.
>>
>> - Michael Spencer