doxygen: make dox

Add an optional make target (make dox) and doxygen configuration to
generate doxygen output files.  Auto-detect when the doxygen and
graphviz dot tools are available.  When dot is present, configure
doxygen to create dependency graphs.

Since the graph generation can take a very long time, a new
configure option has been added to override the dot tool
auto-detection. To disable the graph generation (even if dot is
installed), run configure with the option: --without-dot

When graph generation is desired, but graphviz dot is not present in
the PATH, specify the path to dot with the configure option
--with-dot=<path-to-dot>.

The configure summary has been updated to show when doxygen document
and graph generation is configured.

Thank you Jason Edgecombe for providing the doxygen configuration
for OpenAFS.

Change-Id: Ie875fc2961877ee76e4c17631bbb95c29ef20b9e
Reviewed-on: http://gerrit.openafs.org/10970
Tested-by: BuildBot <buildbot@rampaginggeek.com>
Reviewed-by: D Brashear <shadow@your-file-system.com>

diff --git a/Makefile.in b/Makefile.in
index 56faa91..c077a0e 100644 (file)
--- a/Makefile.in
+++ b/Makefile.in
@@ -11,6 +11,7 @@ srcdir=@srcdir@
 include @TOP_OBJDIR@/src/config/Makefile.config
 
 ENABLE_KERNEL_MODULE=@ENABLE_KERNEL_MODULE@
+DOXYGEN=@DOXYGEN@
 
 # To compile AFS from scratch in the src tree run "make".
 #   This recursively calls "make install ..." and does not depend on the
@@ -780,6 +781,11 @@ dist:
 srpm:
        (cd packages && ../src/packaging/RedHat/makesrpm.pl *-src.tar.bz2 *-doc.tar.bz2)
 
+dox:
+       if test "x$(DOXYGEN)" != "x"; then \
+           mkdir -p doc/doxygen/output && $(DOXYGEN) doc/doxygen/Doxyfile; \
+       fi
+
 distclean: clean
        /bin/rm -rf lib include packages
        /bin/rm -f config.log config.cache config.status \

diff --git a/acinclude.m4 b/acinclude.m4
index 7e02450..9228ac2 100644 (file)
--- a/acinclude.m4
+++ b/acinclude.m4
@@ -277,11 +277,36 @@ AC_ARG_WITH([docbook-stylesheets],
                AC_WARN([Docbook stylesheets not found; some documentation can't be built])
        fi)
 
+AC_ARG_WITH([dot],
+       AS_HELP_STRING([--with-dot@<:@=PATH@:>@],
+        [use graphviz dot to generate dependency graphs with doxygen (defaults to autodetect)]),
+        [], [with_dot="maybe"])
+
 enable_login="no"
 
 dnl Check whether kindlegen exists.  If not, we'll suppress that part of the
 dnl documentation build.
 AC_CHECK_PROGS([KINDLEGEN], [kindlegen])
+AC_CHECK_PROGS([DOXYGEN], [doxygen])
+
+dnl Optionally generate graphs with doxygen.
+case "$with_dot" in
+maybe)
+    AC_CHECK_PROGS([DOT], [dot])
+    AS_IF([test "x$DOT" = "x"], [HAVE_DOT="no"], [HAVE_DOT="yes"])
+    ;;
+yes)
+    HAVE_DOT="yes"
+    ;;
+no)
+    HAVE_DOT="no"
+    ;;
+*)
+    HAVE_DOT="yes"
+    DOT_PATH=$with_dot
+esac
+AC_SUBST(HAVE_DOT)
+AC_SUBST(DOT_PATH)
 
 dnl Checks for UNIX variants.
 AC_ISC_POSIX

diff --git a/configure.ac b/configure.ac
index 81a677a..94190eb 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -132,6 +132,9 @@ AS_IF([test -f 'doc/xml/AdminRef/Makefile.in'],
 AS_IF([test -f 'doc/xml/mobi-fixup.xsl.in'],
     [MOBI_FIXUP_XSL="doc/xml/mobi-fixup.xsl"],
     [MOBI_FIXUP_XSL=])
+AS_IF([test -f 'doc/doxygen/Doxyfile.in'],
+    [DOXYFILE="doc/doxygen/Doxyfile"],
+    [DOXYFILE=])
 
 AC_OUTPUT([
     Makefile
@@ -141,6 +144,7 @@ AC_OUTPUT([
     ${USERGUIDE_MAKEFILE}
     ${ADMINREF_MAKEFILE}
     ${MOBI_FIXUP_XSL}
+    ${DOXYFILE}
     src/afs/Makefile
     src/afsd/Makefile
     src/afsmonitor/Makefile

diff --git a/doc/doxygen/.gitignore b/doc/doxygen/.gitignore
new file mode 100644 (file)
index 0000000..43cb5d6
--- /dev/null
+++ b/doc/doxygen/.gitignore
@@ -0,0 +1,3 @@
+Makefile
+Doxyfile
+output/

diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in
new file mode 100644 (file)
index 0000000..30e3d55
--- /dev/null
+++ b/doc/doxygen/Doxyfile.in
@@ -0,0 +1,60 @@
+#
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for OpenAFS.
+#
+
+PROJECT_NAME           = "OpenAFS"
+PROJECT_BRIEF          = "OpenAFS distributed network file system"
+PROJECT_LOGO           = src/WINNT/afsd/OpenAFS.ico
+OUTPUT_DIRECTORY       = doc/doxygen/output
+
+ABBREVIATE_BRIEF       = "The $name class" "The $name widget" "The $name file" \
+                          is provides specifies contains represents a an the
+QT_AUTOBRIEF           = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+SYMBOL_CACHE_SIZE      = 7
+LOOKUP_CACHE_SIZE      = 2
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
+
+GENERATE_DOCSET        = YES
+GENERATE_TREEVIEW      = YES
+GENERATE_LATEX         = NO
+
+DOCSET_BUNDLE_ID       = org.openafs.Project
+DOCSET_PUBLISHER_ID    = org.openafs.Publisher
+QHP_NAMESPACE          = org.openafs.Project
+ECLIPSE_DOC_ID         = org.openafs.Project
+
+HAVE_DOT               = @HAVE_DOT@
+DOT_PATH               = @DOT_PATH@
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+
+EXTRACT_ALL            = YES
+INPUT                  = doc/doxygen/input src
+RECURSIVE              = YES
+EXCLUDE                = \
+    src/cf \
+    src/config \
+    src/dviced \
+    src/dvolser \
+    src/external \
+    src/finale \
+    src/JAVA \
+    src/kauth \
+    src/libafs \
+    src/mcas \
+    src/NTObjdir \
+    src/packaging \
+    src/shlibafsrpc \
+    src/tbudb \
+    src/tbutc \
+    src/tests \
+    src/tools \
+    src/tptserver \
+    src/tsalvaged \
+    src/tubik \
+    src/tvlserver \
+    src/tvolser \
+

diff --git a/src/cf/summary.m4 b/src/cf/summary.m4
index ec180e1..111b22c 100644 (file)
--- a/src/cf/summary.m4
+++ b/src/cf/summary.m4
@@ -45,10 +45,16 @@ AC_DEFUN([OPENAFS_SUMMARY],[
   AS_IF([test "x${DOCBOOK_STYLESHEETS}" = "x"],
     [summary_docbook_stylesheets="no"],
     [summary_docbook_stylesheets="yes"])
+  AS_IF([test "x${DOXYGEN}" = "x"],
+    [summary_doxygen="no"],
+    [summary_doxygen="yes"])
+  AS_IF([test "${summary_doxygen}" = "yes" -a "${HAVE_DOT}" = "yes"],
+    [summary_doxygen_graphs="yes"],
+    [summary_doxygen_graphs="no"])
 
   cat <<EOF
 ***************************************************************
-configure summary
+OpenAFS configure summary
 
   version : ${VERSION}
   sysname : ${AFS_SYSNAME}
@@ -56,7 +62,6 @@ configure summary
 debug:
   userspace              : ${enable_debug}
   kernel                 : ${enable_debug_kernel}
-
 options:
   transarc paths         : ${enable_transarc_paths}
   namei fileserver       : ${openafs_cv_summary_check_namei}
@@ -64,14 +69,15 @@ options:
   ptserver supergroups   : ${enable_supergroups}
   pthreaded ubik         : ${enable_pthreaded_ubik}
   install kauth          : ${INSTALL_KAUTH}
-  docbook stylesheets    : ${summary_docbook_stylesheets}
-
 build:
   scout/afsmonitor       : ${summary_build_scout}
   pam                    : ${HAVE_PAM}
   login                  : ${BUILD_LOGIN}
   uss                    : ${BUILD_USS}
-
+doc generation:
+  docbook stylesheets    : ${summary_docbook_stylesheets}
+  doxygen                : ${summary_doxygen}
+  doxygen graphs         : ${summary_doxygen_graphs}
 libraries:
   krb5    : ${KRB5_LIBS}
   curses  : ${LIB_curses}