[PATCH] Allow CMake to build Sphinx documentation

[Reid Kleckner]

On Tue, Apr 15, 2014 at 3:25 PM, 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 agree. This is more complicated than necessary.  I'd love it if we had a
'docs' target that generated html output identical to what we publish on
the web in ${build}/docs.  We don't need any other targets other than
clang-docs and maybe lld-docs.


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

I don't think our current docs are useful as man pages.  We'd want to make
stripped down docs for each of the tools (llc, opt, clang), and try to
document all the options.  Nobody needs 'man llvmLangRef' or 'man
llvmInAlloca'.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140415/c3423a60/attachment.html>