[PATCH] Allow CMake to build Sphinx documentation

[Dan Liew]

Just to note I've switched to using a different e-mail address with
the mailing lists.

On 15 April 2014 23:25, Sean Silva <chisophugis at gmail.com> wrote:
> Thanks for the patch. I love the direction but I think it can be simplified
> quite a bit using the following information:
>
> Note that Makefile.sphinx is just a "boilerplate" file generated by
> "sphinx-quickstart" and not integrated in any way with LLVM's build system.
> We don't need all the functionality in Makefile.sphinx; in fact, we really
> only need the default (`html`) (and clean obviously; and maybe `man` once we
> rig up the install of the manpages).

I could certainly remove some of the targets. My guess was that only
the html targets were used but I wasn't sure so I added some of the
other targets (.e.g text, epub and man).

> I don't think it is a good idea to add "linkcheck" as part of the build for
> two reasons:
> 1. we don't want the build to require an internet connection
> 2. we don't want to allow the content of an external website (which may
> change arbitrarily) to break the build.
> Also, it's just not an actionable thing for your average developer.
>
> Let's see what the patch looks like taking that into account.

Would you prefer if I removed this target entirely? It is currently
always off unless someone explicitly enables it.

> Btw, Thanks for tackling issues at the intersection of the docs and the
> build system. Very brave. If you understand how the CMake install works, it
> would be a godsend to have it install the manpages (generated by Sphinx's
> `-b man`) as part of the usual install (if the docs were built, of course).

I would need to study this a little more. Currently if
SPHINX_OUTPUT_MAN is enabled we seem to generate .1 files for each
llvm tool (I'm not quite sure how sphinix knows to only generate man
pages for these). I guess the remaining task is to install these in
the usual location.

Thanks,
-- 
Dan Liew
PhD Student - Imperial College London