[PATCH] Allow CMake to build Sphinx documentation

[Sean Silva]

On Tue, Apr 15, 2014 at 6:38 PM, Reid Kleckner <rnk at google.com> wrote:

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

It's not integrated with the build, but `cd docs/; make -f Makefile.sphinx;
$BROWSER _build/html/foo.html` will do that if you need it now. See
docs/README.txt for more information.

Personally I don't mind have the docs build decoupled from the regular
build; it's convenient in some respects. However, I definitely see the
appeal of having it integrated into the regular build as well and am all
for it (for one, it would get a bit more attention paid to the docs as it
would seamlessly fit in with the usual workflow).


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

I mean the stuff in docs/CommandGuide/, which are specifically man pages
(see docs/README.txt). Those are the only ones that get built by the man
target (see conf.py:215).

-- Sean Silva
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140417/153bb7fe/attachment.html>