[PATCH] Allow CMake to build Sphinx documentation

[Sean Silva]

On Thu, Apr 17, 2014 at 5:58 PM, 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).
>

I didn't know about it either and it does seem like it would be useful in
some situations. However, I don't consider it that important. Even in the
category of "lots of by-hand mechanical work" it isn't a top priority (a
much bigger thing in that category is fixing up internal HTML links to be
:ref: or :doc: links so that Sphinx knows about them).

That's not to say that I wouldn't be glad to accept patches fixing broken
links (especially any in CompilerWriterInfo). But if you have a nontrivial
amount of experience with LLVM it is much preferred if you contributed
actual content to the documentation based on your knowledge.


>
> Would it be okay to add information about how to check links manually
> to http://llvm.org/docs/SphinxQuickstartTemplate.html as a separate
> patch?
>

SphinxQuickstartTemplate is not the right place for that kind of
information: one of its goals is getting people to write quality content
with "as little nonsense as possible". Worrying about a broken link is
nonsense compared to writing quality content. I would probably be fine with
a note at the bottom of docs/README.txt.


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

Seems fine to me.


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

Give it a spin on clang as a sanity check (and if you have spare cycles,
lld too). I don't think lldb uses sphinx. Since this is gated behind an
option, I wouldn't worry about out-of-tree builds.

Oh, btw, when I applied your patch last time git gave me some trailing
whitespace warnings. Please try to avoid trailing whitespace.

-- Sean Silva


>
>
> > 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140418/dd0f2434/attachment.html>