[PATCH] Added doxygen support for the tools of clang-tools-extra repo

[Sean Silva]

On Wed, Feb 27, 2013 at 2:04 PM, Vane, Edwin <edwin.vane at intel.com> wrote:
> I'm a little confused about these various documentation threads. Let me recap my understanding.
>
> The goal is to get sphinx and doxygen being generated for clang-tools-extra. Currently, none of llvm/clang/extra can generate these docs via cmake and are using the autoconf system to generate docs into the source tree. Llvm/clang are generating doxygen docs in a way  silvas doesn't like (referring to the thread about not having Doxygen.intro, and non-standard CSS, etc.) and would like tools-extra to generate Doxygen in a better way as a trailblazer. Is this all correct?

Not quite: the Sphinx build for LLVM and Clang is completely
independent of the build system ({llvm,clang}/docs/Makefile.sphinx is
not connected with autoconf in any way) and are generated in the
source tree. Their doxygen builds *are* dependent on autoconf and are
*not* generated in the source tree. Other than that, everything you
said is correct.

> Silvas says generating docs to the build dir is a big deal that requires lots of input. Shall we begin a discussion on cfe-dev then?

It's not really clear that generating to the build dir is even
actually preferable. I really only mentioned the option of tying into
the build as an "if we ever actually need it, then it will need to be
discussed" sort of thing.

I don't see a compelling reason currently that the documentation
should be different depending on the build settings; it should depend
solely on the source tree, so it makes sense to have the documentation
generated based solely on the source tree and in a fixed place in the
source tree. Decoupling it from the build system also makes the
documentation easier to build, which (particularly for the Sphinx
docs) improves the chances of someone actually contributing to the
docs.

Generating them in-tree like this also has a nice "mechanism, not
policy" feel. Generating the docs is the bulk of the work (and is what
we are discussing right now); involving the build systems would just
add a lot of complexity and uncertainty ("how do I do this in both
CMake and autoconf? is it even possible?"), when really the only
reason the build system needs to be involved is to choose the output
directory. Once "generating the docs" is set up, then it is really
very simple later on to point the generator programs to a different
output directory if someone feels like doing the leg work to do that
(e.g. so that the "install" target actually works). In the meantime,
it is not difficult for packagers to generate the docs in-tree and
copy them wherever they feel like.

So basically, I don't really think that it is in need of discussion at
the moment.

One example where we would need to have build information is if there
were some clang-based doxygen replacement that fully parses the entire
program from scratch, but we don't currently rely on such a tool to
generate our documentation.

-- Sean Silva