[PATCH] Allow CMake to build Sphinx documentation

[Reid Kleckner]

Thanks! I committed these in r206655, r206660, and r206662.

I tested the LLVM and clang docs and fixed some issues, but I'm not set up
to build lld on Linux at the moment.

This didn't work for me on Windows because sphinx-build isn't an exe.  The
right fix is probably to prefix the command with ${PYTHON_EXECUTABLE}, but
that can be separate.

I also made the output quiet (-q) and made warnings into errors (-W), since
this is really what we want in a build.


On Fri, Apr 18, 2014 at 2:22 PM, Dan Liew <dan at su-root.co.uk> wrote:

> Okay here is the third version of the patch. I've removed the
> docs-llvm-linkcheck target and I've changed the add_sphinx_target()
> function so that the project name is specified as the second argument.
> This is necessary because when clang and lld are built inside the LLVM
> source tree they don't call ``project()`` and so CMAKE_PROJECT_NAME is
> still LLVM and so this would cause problems because
> add_sphinx_target() would try to create another target with the same
> name.
>
> I've also attached a rough patch for clang and lld which allows their
> documentation to be built and installed too provided the following
> conditions are met
>
> * LLVM_SPHINX_ENABLE and LLVM_BUILD_DOCS are enabled
> * lld and clang are inside the LLVM source tree (i.e. located at
> tools/lld and tools/clang)
>
> I realise patches to clang and lld need to go to their respective
> mailing lists but I thought I would show these to prove that the
> add_sphinx_target() function could be reused across projects. If my
> LLVM patch gets into trunk then we can look into getting the clang and
> lld patches into their respective projects.
>
> Unfortunately building documentation for Clang or lld won't work if
> Clang or lld are being built against LLVM as a library because the
> LLVM CMake variables (e.g. LLVM_SPHINX_ENABLE) will not be set and the
> add_sphinx_target() function won't be available. Maintainers of Clang
> and lld would need to include their own copy of AddSphinxTarget.cmake
> and have their own variables to enable building documentation to
> support this.
>
> Thanks,
> Dan.
>
> On 17 April 2014 22:58, Dan Liew <dan at su-root.co.uk> wrote:
> >> This is looking really good. I would like to remove the linkcheck target
> >> just on the principle that the build should not go accessing external
> >> websites.
> >
> > Sure. I feel as if users should still be made aware of this feature (I
> > certainly didn't know about it before I started this work).
> >
> > Would it be okay to add information about how to check links manually
> > to http://llvm.org/docs/SphinxQuickstartTemplate.html as a separate
> > patch?
> >
> > Since I'm going to rework the patch again I'd like to ask people's
> > opinions on a few things before I start
> >
> > - Are the names of the targets okay?
> >
> > * docs-llvm-html
> > * docs-llvm-man
> >
> > i.e. if you build with LLVM_ENABLE_SPHINX you can type ``make
> > docs-llvm-html`` and ``make docs-llvm-man`` to build documentation.
> >
> > - I've assumed the add_sphinx_target() function is reusable by other
> > projects like Clang and lldb. This might not be the case depending on
> > how these projects interact with LLVM's CMake build system. I've only
> > ever built Clang inside the LLVM tree (a case where reusing
> > add_sphinx_target should work) but I'm sure I remember reading
> > somewhere that Clang can be built out of tree and in that case I have
> > doubts about reusing add_sphinx_target() working. I've never even
> > built lldb but the instructions seem to say I should build in tree.
> >
> >  Would it be worth trying to apply the add_sphinx_target() functin to
> > Clang and lldb as well?
> >
> >
> >> You should send 0002 in a separate patch thread. I don't really have the
> >> knowledge to sign off on it. I think you'll want to CC chapuni or
> chandler.
> >
> > Sure I'll do that.
> >
> > Thanks,
> > --
> > Dan Liew
> > PhD Student - Imperial College London
>
>
>
> --
> Dan Liew
> PhD Student - Imperial College London
>
> _______________________________________________
> 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/20140418/3568ff8c/attachment.html>