changeset 16246:98d8d1f4b7f8

build: Add creation of Doxygen docs to build system * configure.ac: Add doc/doxyhtml/Makefile to list of Makefiles to generate. * Doxyfile: Moved and renamed to doc/doxyhtml/Doxygen.cfg. * doc/Makefile.am: Add doxyhtml directory to list of SUBDIRS. * doc/doxyhtml/Doxygen.cfg: Renamed from Doxyfile at top-level. * doc/doxyhtml/Makefile.am: New Makefile.am with rules for building and cleaning Doxygen documentation * doc/doxyhtml/README: README file explaining how to build optional Doxygen documentation.
author Rik <rik@octave.org>
date Mon, 11 Mar 2013 10:49:44 -0700
parents b1b01c69967e
children 4dc4da5970e5
files Doxyfile configure.ac doc/Makefile.am doc/doxyhtml/Doxygen.cfg doc/doxyhtml/Makefile.am doc/doxyhtml/README
diffstat 6 files changed, 312 insertions(+), 268 deletions(-) [+]
line wrap: on
line diff
--- a/Doxyfile	Mon Mar 11 09:03:56 2013 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,267 +0,0 @@
-# -*- mode: conf; -*-
-
-# Doxyfile for Doxygen 1.7.1
-
-# This file describes the settings to be used by the documentation system
-# doxygen (www.doxygen.org) for GNU Octave.
-#
-# All text after a hash (#) is considered a comment and will be ignored
-# The format is:
-#       TAG = value [value, ...]
-# For lists items can also be appended using:
-#       TAG += value [value, ...]
-# Values that contain spaces should be placed between quotes (" ")
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-
-# This tag specifies the encoding used for all characters in the
-# config file that follow. We don't use anything but ASCII, but
-# there's no problem using UTF-8 from now on
-
-DOXYFILE_ENCODING      = UTF-8
-
-# Who we are. :-)
-
-PROJECT_NAME           = "GNU Octave"
-
-# The public stable API version (unrelated to the internal API
-# version).
-
-PROJECT_NUMBER         = 3.7
-
-# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
-# base path where the generated documentation will be put.
-
-OUTPUT_DIRECTORY       = doc/
-
-# Create 4096 sub-directories (in 2 levels) under the output directory
-# of each output format and will distribute the generated files over
-# these directories. Enabling this option is useful for us, since
-# feeding doxygen a huge amount of source files would put all
-# generated files in the same directory would otherwise cause
-# performance problems for the file system.
-
-CREATE_SUBDIRS         = YES
-
-# The OUTPUT_LANGUAGE tag is used to specify the language in which all
-# documentation generated by doxygen is written.
-
-OUTPUT_LANGUAGE        = English
-
-# Include brief member descriptions after the members that are listed
-# in the file and class documentation (similar to JavaDoc). Set to NO
-# to disable this.
-
-BRIEF_MEMBER_DESC      = YES
-
-# Prepend the brief description of a member or function before the
-# detailed description. Note: if both HIDE_UNDOC_MEMBERS and
-# BRIEF_MEMBER_DESC are set to NO, the brief descriptions will be
-# completely suppressed.
-
-REPEAT_BRIEF           = YES
-
-# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
-# Doxygen will generate a detailed section even if there is only a brief
-# description.
-
-ALWAYS_DETAILED_SEC    = NO
-
-# Show inherited members as if they were part of the current class
-
-INLINE_INHERITED_MEMB  = YES
-
-# Prepend the full path before files name in the file list and in the
-# header files.
-
-FULL_PATH_NAMES        = YES
-
-# Interpret the first line (until the first dot) of a JavaDoc-style
-# comment as the brief description (without needing the @brief
-# command).
-
-JAVADOC_AUTOBRIEF      = YES
-
-# Interpret the first line (until the first dot) of a Qt-style comment
-# as the brief descriptio (without needing the \brief command).
-
-QT_AUTOBRIEF           = NO
-
-# Undocumented member inherits the documentation from any documented
-# member that it re-implements.
-
-INHERIT_DOCS           = YES
-
-# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
-# a new page for each member. If set to NO, the documentation of a member will
-# be part of the file/class/namespace that contains it.
-
-SEPARATE_MEMBER_PAGES  = NO
-
-# The TAB_SIZE tag can be used to set the number of spaces in a tab.
-# Doxygen uses this value to replace tabs by spaces in code fragments.
-# We shouldn't have any tabs in the source code to begin with, however.
-
-TAB_SIZE               = 2
-
-# Figure out C++ stdlib classes without needing to parse those files.
-
-BUILTIN_STL_SUPPORT    = YES
-
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-
-# Assume all entities in documentation are documented, even if no
-# documentation was available.
-
-EXTRACT_ALL            = YES
-
-# Include all private members of a class.
-
-EXTRACT_PRIVATE        = YES
-
-# Include  all static members of a file.
-
-EXTRACT_STATIC         = YES
-
-# Include classes (and structs) defined locally in source files in the
-# documentation.
-
-EXTRACT_LOCAL_CLASSES  = YES
-
-# We don't use namespaces, but if we did, this would extract the
-# anonymous one.
-
-EXTRACT_ANON_NSPACES   = YES
-
-# Hide internal docs, those with the \internal command.
-
-INTERNAL_DOCS          = NO
-
-# Case-sensitive filenames
-
-CASE_SENSE_NAMES       = YES
-
-# List include files with double quotes in the documentation rather
-# than with sharp brackets.
-
-FORCE_LOCAL_INCLUDES   = YES
-
-# Show members alphabetically
-
-SORT_MEMBER_DOCS       = YES
-
-# Also sort the brief descriptions
-
-SORT_BRIEF_DOCS        = YES
-
-# Put ctors first.
-
-SORT_MEMBERS_CTORS_1ST = YES
-
-# Show which directories the file is in.
-
-SHOW_DIRECTORIES       = YES
-
-# We don't have namespaces, so don't show them.
-
-SHOW_NAMESPACES        = NO
-
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-
-# Which directories contain Octave source code
-
-INPUT                  = src/ liboctave/ libinterp/
-
-# Search subdirectories for input.
-
-RECURSIVE              = YES
-
-# Our examples.
-
-EXAMPLE_PATH           = 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
-# and *.h) to filter out the source-files in the directories. If left
-# blank all files are included.
-
-EXAMPLE_PATTERNS       =
-
-# There are no extra C++ files in the examples subdir
-
-EXAMPLE_RECURSIVE      = NO
-
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-
-# Generate a list of source files will be generated.
-
-SOURCE_BROWSER         = YES
-
-# Setting the INLINE_SOURCES tag to YES will include the body
-# of functions and classes directly in the documentation.
-
-INLINE_SOURCES         = NO
-
-# Hide any special comment blocks from generated source code
-# fragments. Normal C and C++ comments will always remain visible.
-
-STRIP_CODE_COMMENTS    = YES
-
-# For each documented function, list all documented functions
-# referencing it.
-
-REFERENCED_BY_RELATION = YES
-
-# For each documented function all documented entities called/used by
-# that function will be listed.
-
-REFERENCES_RELATION    = YES
-
-# References link to documenation, not source code.
-
-REFERENCES_LINK_SOURCE = NO
-
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-
-# Generate HTML
-
-GENERATE_HTML          = YES
-
-# i.e. doc/doxyhtml
-
-HTML_OUTPUT            = doxyhtml
-
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-
-# No LaTeX
-
-GENERATE_LATEX         = NO
-
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-
-# Show undocumented relations
-
-HIDE_UNDOC_RELATIONS   = NO
-
-# Use dot from graphviz to generate class diagrams.
-
-HAVE_DOT               = YES
-
-# Remove intermediate dot files.
-
-DOT_CLEANUP            = YES
-
--- a/configure.ac	Mon Mar 11 09:03:56 2013 -0700
+++ b/configure.ac	Mon Mar 11 10:49:44 2013 -0700
@@ -2857,6 +2857,7 @@
 AC_CONFIG_FILES([
   Makefile 
   doc/Makefile
+  doc/doxyhtml/Makefile
   doc/icons/Makefile
   doc/interpreter/Makefile
   doc/liboctave/Makefile
--- a/doc/Makefile.am	Mon Mar 11 09:03:56 2013 -0700
+++ b/doc/Makefile.am	Mon Mar 11 10:49:44 2013 -0700
@@ -29,5 +29,5 @@
   texinfo.tex \
   texmf.cnf
 
-SUBDIRS = icons interpreter liboctave refcard
+SUBDIRS = doxyhtml icons interpreter liboctave refcard
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/doxyhtml/Doxygen.cfg	Mon Mar 11 10:49:44 2013 -0700
@@ -0,0 +1,267 @@
+# -*- mode: conf; -*-
+
+# Doxyfile for Doxygen 1.7.1
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for GNU Octave.
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+#       TAG = value [value, ...]
+# For lists items can also be appended using:
+#       TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# This tag specifies the encoding used for all characters in the
+# config file that follow. We don't use anything but ASCII, but
+# there's no problem using UTF-8 from now on
+
+DOXYFILE_ENCODING      = UTF-8
+
+# Who we are. :-)
+
+PROJECT_NAME           = "GNU Octave"
+
+# The public stable API version (unrelated to the internal API
+# version).
+
+PROJECT_NUMBER         = 3.7
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+
+OUTPUT_DIRECTORY       = doc/
+
+# Create 4096 sub-directories (in 2 levels) under the output directory
+# of each output format and will distribute the generated files over
+# these directories. Enabling this option is useful for us, since
+# feeding doxygen a huge amount of source files would put all
+# generated files in the same directory would otherwise cause
+# performance problems for the file system.
+
+CREATE_SUBDIRS         = YES
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written.
+
+OUTPUT_LANGUAGE        = English
+
+# Include brief member descriptions after the members that are listed
+# in the file and class documentation (similar to JavaDoc). Set to NO
+# to disable this.
+
+BRIEF_MEMBER_DESC      = YES
+
+# Prepend the brief description of a member or function before the
+# detailed description. Note: if both HIDE_UNDOC_MEMBERS and
+# BRIEF_MEMBER_DESC are set to NO, the brief descriptions will be
+# completely suppressed.
+
+REPEAT_BRIEF           = YES
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC    = NO
+
+# Show inherited members as if they were part of the current class
+
+INLINE_INHERITED_MEMB  = YES
+
+# Prepend the full path before files name in the file list and in the
+# header files.
+
+FULL_PATH_NAMES        = YES
+
+# Interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description (without needing the @brief
+# command).
+
+JAVADOC_AUTOBRIEF      = YES
+
+# Interpret the first line (until the first dot) of a Qt-style comment
+# as the brief descriptio (without needing the \brief command).
+
+QT_AUTOBRIEF           = NO
+
+# Undocumented member inherits the documentation from any documented
+# member that it re-implements.
+
+INHERIT_DOCS           = YES
+
+# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
+# a new page for each member. If set to NO, the documentation of a member will
+# be part of the file/class/namespace that contains it.
+
+SEPARATE_MEMBER_PAGES  = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+# We shouldn't have any tabs in the source code to begin with, however.
+
+TAB_SIZE               = 2
+
+# Figure out C++ stdlib classes without needing to parse those files.
+
+BUILTIN_STL_SUPPORT    = YES
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# Assume all entities in documentation are documented, even if no
+# documentation was available.
+
+EXTRACT_ALL            = YES
+
+# Include all private members of a class.
+
+EXTRACT_PRIVATE        = YES
+
+# Include  all static members of a file.
+
+EXTRACT_STATIC         = YES
+
+# Include classes (and structs) defined locally in source files in the
+# documentation.
+
+EXTRACT_LOCAL_CLASSES  = YES
+
+# We don't use namespaces, but if we did, this would extract the
+# anonymous one.
+
+EXTRACT_ANON_NSPACES   = YES
+
+# Hide internal docs, those with the \internal command.
+
+INTERNAL_DOCS          = NO
+
+# Case-sensitive filenames
+
+CASE_SENSE_NAMES       = YES
+
+# List include files with double quotes in the documentation rather
+# than with sharp brackets.
+
+FORCE_LOCAL_INCLUDES   = YES
+
+# Show members alphabetically
+
+SORT_MEMBER_DOCS       = YES
+
+# Also sort the brief descriptions
+
+SORT_BRIEF_DOCS        = YES
+
+# Put ctors first.
+
+SORT_MEMBERS_CTORS_1ST = YES
+
+# Show which directories the file is in.
+
+SHOW_DIRECTORIES       = YES
+
+# We don't have namespaces, so don't show them.
+
+SHOW_NAMESPACES        = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# Which directories contain Octave source code
+
+INPUT                  = src/ liboctave/ libinterp/
+
+# Search subdirectories for input.
+
+RECURSIVE              = YES
+
+# Our examples.
+
+EXAMPLE_PATH           = 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
+# and *.h) to filter out the source-files in the directories. If left
+# blank all files are included.
+
+EXAMPLE_PATTERNS       =
+
+# There are no extra C++ files in the examples subdir
+
+EXAMPLE_RECURSIVE      = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# Generate a list of source files will be generated.
+
+SOURCE_BROWSER         = YES
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES         = NO
+
+# Hide any special comment blocks from generated source code
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS    = YES
+
+# For each documented function, list all documented functions
+# referencing it.
+
+REFERENCED_BY_RELATION = YES
+
+# For each documented function all documented entities called/used by
+# that function will be listed.
+
+REFERENCES_RELATION    = YES
+
+# References link to documenation, not source code.
+
+REFERENCES_LINK_SOURCE = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# Generate HTML
+
+GENERATE_HTML          = YES
+
+# i.e. doc/doxyhtml
+
+HTML_OUTPUT            = doxyhtml
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# No LaTeX
+
+GENERATE_LATEX         = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+# Show undocumented relations
+
+HIDE_UNDOC_RELATIONS   = NO
+
+# Use dot from graphviz to generate class diagrams.
+
+HAVE_DOT               = YES
+
+# Remove intermediate dot files.
+
+DOT_CLEANUP            = YES
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/doxyhtml/Makefile.am	Mon Mar 11 10:49:44 2013 -0700
@@ -0,0 +1,32 @@
+# 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
+
+doxyhtml:
+	cd ../..; doxygen doc/doxyhtml/Doxygen.cfg 
+
+EXTRA_DIST = \
+  Doxygen.cfg \
+  Makefile.am \
+  README
+
+maintainer-clean-local:
+	rm -rf `ls | $(GREP) -v Doxygen.cfg | $(GREP) -v Makefile.am | $(GREP) -v Makefile.in | $(GREP) -v README`
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/doxyhtml/README	Mon Mar 11 10:49:44 2013 -0700
@@ -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.