[llvm-commits] Unbork Sphinx docs build

[Michael Spencer]

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