[PATCH] Allow CMake to build Sphinx documentation

Dan Liew dan at su-root.co.uk
Tue Apr 15 17:52:08 PDT 2014


On 15 April 2014 23:38, 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.

In my patch this target is currently called sphinx-llvm-html. I could
change it but I'm not sure "docs" is appropriate because it might be
confused with doxygen by the user. Perhaps "docs" should be high level
target that invokes building doxygen docs (if LLVM_ENABLE_DOXYGEN is
enabled) and the sphinx docs (if LLVM_ENABLE_SPHINX is enabled)?

Currently the pages are built in ${CMAKE_BINARY_DIR}/docs/_build/html
. Building html documentation in ${CMAKE_BINARY_DIR}/docs would
unfortunately stop make clean from working because I do not know what
files sphinx might generate so it is easier for everything to go in a
separate directory and then have ``make clean`` just delete that
directory.

I'm happy to change the location to somewhere else, perhaps
${CMAKE_BINARY_DIR}/docs/html ?

>>
>> 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'm not sure why but running ``sphinx -b man`` only generates man
pages for the pages in doc/CommandGuide/ (i.e. only the LLVM tools).
There are no man pages for things like the language reference.

This will hopefully mean that installing man pages "should" be easy.

Thanks,
-- 
Dan Liew
PhD Student - Imperial College London



More information about the llvm-commits mailing list