changeset 17104:c48625614ea6 stable

Properly incorporate Doxygen into the build system * Doxyfile.in: Rename from Doxyfile and move to doc/doxyhtml directory. Templatise properly with autoconf macros. Configuration tweaks: expand DEFUN macros, show namespaces, document the GUI sources, don't strip Doxygen comments from the source, allow dot to create larger graphs. Also add a a tagline and the Octave logo. * doc/doxyhtml/README: New file, grafted from the dev branch. * doc/doxyhtml/Makefile.am: New file, handles doxyhtml target. * Makefile.am: Add doxyhtml target. * configure.ac: Add doxyhtml files to AC_CONFIG_FILES
author Jordi Gutiérrez Hermoso <jordigh@octave.org>
date Sun, 28 Jul 2013 01:18:48 -0400
parents f2f5dd09e97d
children fa3f2ac0e825
files Doxyfile Makefile.am configure.ac doc/doxyhtml/Doxyfile.in doc/doxyhtml/Makefile.am doc/doxyhtml/README
diffstat 5 files changed, 83 insertions(+), 15 deletions(-) [+]
line wrap: on
line diff
--- a/Makefile.am
+++ b/Makefile.am
@@ -128,6 +128,10 @@
 	mv $@.t $@
 .PHONY: ChangeLog
 
+doxyhtml:
+	$(MAKE) -C doc/doxyhtml
+.PHONY: doxyhtml
+
 octetc_DATA = NEWS
 
 DIRS_TO_MAKE = \
--- a/configure.ac
+++ b/configure.ac
@@ -2177,6 +2177,8 @@
   Makefile 
   doc/Makefile
   doc/faq/Makefile
+  doc/doxyhtml/Makefile
+  doc/doxyhtml/Doxyfile
   doc/icons/Makefile
   doc/interpreter/Makefile
   doc/liboctave/Makefile
rename from Doxyfile
rename to doc/doxyhtml/Doxyfile.in
--- a/Doxyfile
+++ b/doc/doxyhtml/Doxyfile.in
@@ -26,15 +26,21 @@
 
 PROJECT_NAME           = "GNU Octave"
 
+PROJECT_BRIEF          =  "A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab"
+
 # The public stable API version (unrelated to the internal API
 # version).
 
-PROJECT_NUMBER         = 3.6
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+
+# Our logo!
+
+PROJECT_LOGO           = @top_srcdir@/doc/icons/octave-logo.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
 # base path where the generated documentation will be put.
 
-OUTPUT_DIRECTORY       = doc/
+OUTPUT_DIRECTORY       = @abs_top_builddir@/doc
 
 # Create 4096 sub-directories (in 2 levels) under the output directory
 # of each output format and will distribute the generated files over
@@ -78,6 +84,10 @@
 
 FULL_PATH_NAMES        = YES
 
+# Remove from the full path names the absolute prefix
+
+STRIP_FROM_PATH        = @top_srcdir@
+
 # Interpret the first line (until the first dot) of a JavaDoc-style
 # comment as the brief description (without needing the @brief
 # command).
@@ -132,6 +142,10 @@
 
 EXTRACT_LOCAL_CLASSES  = YES
 
+# We have very few namespaces, so show the ones we have
+
+SHOW_NAMESPACES        = YES
+
 # We don't use namespaces, but if we did, this would extract the
 # anonymous one.
 
@@ -162,13 +176,13 @@
 
 SORT_MEMBERS_CTORS_1ST = YES
 
-# Show which directories the file is in.
-
-SHOW_DIRECTORIES       = YES
+# Expand the DEFUN family of macros
 
-# We don't have namespaces, so don't show them.
-
-SHOW_NAMESPACES        = NO
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+EXPAND_AS_DEFINED = DEFUN DEFUN_DLD  # As defined in the Octave source
+                                     # code, i.e. not overriden by this
+                                     # config file
 
 #---------------------------------------------------------------------------
 # configuration options related to the input files
@@ -176,7 +190,8 @@
 
 # Which directories contain Octave source code
 
-INPUT                  = src/ liboctave/ libcruft/
+INPUT                  = @top_srcdir@/src/ @top_srcdir@/liboctave/
+INPUT                 += @top_srcdir@/libcruft
 
 # Search subdirectories for input.
 
@@ -184,7 +199,7 @@
 
 # Our examples.
 
-EXAMPLE_PATH           = examples/
+EXAMPLE_PATH           = @top_srcdir@/examples/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -210,10 +225,9 @@
 
 INLINE_SOURCES         = NO
 
-# Hide any special comment blocks from generated source code
-# fragments. Normal C and C++ comments will always remain visible.
+# Don't hide the special Doxygen comment blocks
 
-STRIP_CODE_COMMENTS    = YES
+STRIP_CODE_COMMENTS    = NO
 
 # For each documented function, list all documented functions
 # referencing it.
@@ -225,7 +239,7 @@
 
 REFERENCES_RELATION    = YES
 
-# References link to documenation, not source code.
+# References link to documentation, not source code.
 
 REFERENCES_LINK_SOURCE = NO
 
@@ -237,7 +251,7 @@
 
 GENERATE_HTML          = YES
 
-# i.e. doc/doxyhtml
+# i.e. @abs_top_builddir@/doc/doxyhtml
 
 HTML_OUTPUT            = doxyhtml
 
@@ -265,3 +279,6 @@
 
 DOT_CLEANUP            = YES
 
+# Some of our dependency graphs are really huge...
+
+DOT_GRAPH_MAX_NODES    = 100
\ No newline at end of file
new file mode 100644
--- /dev/null
+++ b/doc/doxyhtml/Makefile.am
@@ -0,0 +1,34 @@
+# Makefile for Octave's doc/doxyhtml directory
+#
+# Copyright (C) 1993-2012 John W. Eaton
+#
+# This file is part of Octave.
+# 
+# Octave is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 3 of the License, or (at
+# your option) any later version.
+# 
+# Octave is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with Octave; see the file COPYING.  If not, see
+# <http://www.gnu.org/licenses/>.
+
+include $(top_srcdir)/build-aux/common.mk
+
+all-local: doxyhtml
+
+doxyhtml:
+	doxygen Doxyfile
+
+EXTRA_DIST = \
+  Doxyfile.in \
+  Makefile.am \
+  README
+
+maintainer-clean-local:
+	rm -rf `ls | $(GREP) -v Doxyfile | $(GREP) -v Makefile.am | $(GREP) -v Makefile.in | $(GREP) -v README`
new file mode 100644
--- /dev/null
+++ b/doc/doxyhtml/README
@@ -0,0 +1,11 @@
+This directory contains documentation in Doxygen format for
+Octave's source code.  It is not created by default.
+
+To produce Doxygen documentation use
+
+make doxyhtml
+
+Doxygen documentation can be helpful for developers of Octave, but is not
+needed by users of Octave.  In addition, the documentation requires
+approximately 1.2GB of storage space.  For these reasons it is not maintained
+under version control nor distributed in tarballs.