[LLVMdev] docs build (doxygen redux)

[mike-m]

Need review on new docs build. The directory layout has changed, and the changes propagate through source, build, install and possible website levels. What follows is an overview of the changes and some reasoning behind them.

[patch can be found under pr6613; you will need doxygen.sh, doxygen.patch, doxygen.txt]
[read: doxygen.txt for full instructions]

A build diagram is also available; left-half is llvm, right is clang:

	http://llvm.org/bugs/attachment.cgi?id=4866

LIGHT-GREEN --> source files
GREEN --> build files (ie: make)
ORANGE --> install files (ie: make install)
RED --> possible new mapping for build-to-website (ie: svn hook scripts)

=== SOURCE TREE

Lots has changed, with intent to clean things up and promote build modularity. In the same fashion which SOURCE/lib/ tree places libraries adjacent to one another, irrespective of their inter-dependencies, this overhaul splits SOURCE/docs/ into two subdirs { main, api } where api/ is specifically for API documentation generated by doxygen. And main/ is everything else.

By splitting the tree, we now how the ability for automagical recursive pickup of files for main/ docs. And the hierarchy is preserved. Files picked up are { .html .css .txt .png .jpg .gif }. For future file extensions we simply need to edit makefile and add to a var. The old system cannot do this, and required nested Makefiles for each directory level. Thus api/ was placed adjacent to main/ given the aforementioned  recursive nature.

SUMMARY LAYOUT CHANGE:
	SOURCE/docs/ -> SOURCE/docs/main/
        SOURCE/docs/ -> SOURCE/docs/api/

	SOURCE/tools/clang/docs/ -> SOURCE/tools/clang/docs/main/
        SOURCE/tools/clang/docs/ -> SOURCE/tools/clang/docs/api/

=== BUILD TREE (objdir)

Build tree is consistent with SOURCE TREE changes. This layout will, if ever desired, easily accommodate M4 or other processing of html files during builds. The old layout, and processes, made too many assumptions that the checked-in files can be used verbatim during install or website update processes. This patch stages everything in a manner that all files and/or tarballs are available for install/website purposes.

Tarballs are a product of 'make' and/or 'make install' and have been named 'html.tar' and 'html-api.tar' for main/ and api/, respectively. The tarball content include prefix pathnames of 'html/' and 'html/api/' for easy extraction by users, distro makers, and the 'make install' process.

Pod files convert to man, html, ps and pdf (new!) files for both build and install situations and the files are suitable for both install and website purposes. Prepatch, the html files generated were unsuitable for install purposes - hardcoded links to root of webserver.

SUMMARY LAYOUT CHANGE: mirrors SOURCE TREE changes

=== INSTALL TREE

Prior to this patch, a 'make install' was unreliable for doxygen (eg: clang failed when gendoc from objdir) and even more confusingly, both llvm and clang would target the same locations in PREFIX dir specified by configure and files would mix-in and overwrite. Many unnecessary files were installed. This is all now fixed. The most notable change here is that except for man pages, llvm and clang will install docs to completely separate points in the tree. The new product points are INSTALL/share/doc/llvm/ and INSTALL/share/doc/clang/ for their respective docs. Naturally, both products still use place man pages into INSTALL/share/man/ as appropriate. Man-page placement honours configure --mandir option. The other placement honours --datarootdir option for the time being. --docdir may prove more appropriate but will require some configure.ac reworking which has yet to be done.

Other targets like 'make uninstall' are useful again. Hint, 'make help' inside main/ or api/ will provide a list of useful targets available. Once nice add is that if you have a objdir already configured, it's possible now to build API docs without reconfiguring --enable-doxygen. You just need to use special target names like 'make docs' instead of 'make'; all documented under 'make help'.

SUMMARY LAYOUT CHANGE:
	INSTALL/share/doc -> INSTALL/share/doc/llvm/
        INSTALL/share/doc -> INSTALL/share/doc/clang/

=== WEBSITE TREE

I don't have visibility into all the details of automatic processes  and directory layouts on the webserver. But *all* the files that are needed by those processes are present. This patch does not remove any files (if it does that's a bug), but it does change the src/build/install layouts. We have a couple of choices here, but I'll offer right up front to enhance the build system with tailored targets for use by any automatic processes. Optionally, stick with the same scripts but update them to work with the new build layout.

===

I realize these layout changes may seem heavy handed, but before passing judgement, I invite reviewers to try the patch. Try building API docs; install them. uninstall them. for your collaborative diagram likers, tune doxygen.cfg.in to your liking, generate again. Switch to clang's docs/ tree. build there. Then try something useful like adding doxygen comments to source code and regenerating the docs to see if doxygen outputs your API doc changes as expected. Hint: 'make help' in any of the OBJDIR docs/ subdirs.

--mike-m