[PATCH] Allow CMake to build Sphinx documentation

[Sean Silva]

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 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.

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).

-- Sean Silva


On Mon, Apr 14, 2014 at 3:36 PM, Daniel Liew <daniel.liew at imperial.ac.uk>wrote:

> Hi,
>
> Attached is a patch (0001) that enables the Sphinx documentation to be
> built when using the CMake build system when LLVM_ENABLE_SPHINX is
> enabled (disabled by default).
>
> I've added quite a few sphinx build targets based on what is in
> docs/Makefile.sphinx but not all because they are more complicated.
> The only sphinx build target enabled by default when
> LLVM_ENABLE_SPHINX is enabled is "sphinx-llvm-html". I'm not sure if
> sphinx-llvm-json or sphinx-llvm-pickle is actually useful.
>
> It would be nice to enable sphinx-llvm-linkcheck by default (when
> LLVM_ENABLE_SPHINX is enabled) so people could be made aware of broken
> links in the documentation but there are already quite a few broken
> links and I don't want to break any builds that might decide to use
> LLVM_ENABLE_SPHINX and LLVM_BUILD_DOCS for now.
>
> I've tested this on Linux with sphinx 1.2.2 with make and Ninja.
>
> Please review.
>
> Thanks,
> Dan.
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140415/936c10e0/attachment.html>