[PATCH] Allow CMake to build Sphinx documentation

[Dan Liew]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: [V3]0001-Added-Sphinx-documentation-generation-to-CMake-build.patch
Type: text/x-patch
Size: 6472 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140418/dc9d8410/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: [clang]0001-Add-support-for-building-Sphinx-documentation-when-b.patch
Type: text/x-patch
Size: 749 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140418/dc9d8410/attachment-0001.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: [lld]0001-Add-support-for-building-Sphinx-documentation-when-b.patch
Type: text/x-patch
Size: 1040 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140418/dc9d8410/attachment-0002.bin>