[llvm-commits] Unbork Sphinx docs build

[Sean Silva]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 01-conf.py.patch
Type: application/octet-stream
Size: 2173 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120819/54a1024a/attachment.obj>