Mercurial > octave-antonio
changeset 17102: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 | 6 files changed, 335 insertions(+), 267 deletions(-) [+] |
line wrap: on
line diff
--- a/Doxyfile Wed May 01 14:41:50 2013 -0400 +++ /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.6 - -# 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/ libcruft/ - -# 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/Makefile.am Wed May 01 14:41:50 2013 -0400 +++ b/Makefile.am Sun Jul 28 01:18:48 2013 -0400 @@ -128,6 +128,10 @@ mv $@.t $@ .PHONY: ChangeLog +doxyhtml: + $(MAKE) -C doc/doxyhtml +.PHONY: doxyhtml + octetc_DATA = NEWS DIRS_TO_MAKE = \
--- a/configure.ac Wed May 01 14:41:50 2013 -0400 +++ b/configure.ac Sun Jul 28 01:18:48 2013 -0400 @@ -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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/doxyhtml/Doxyfile.in Sun Jul 28 01:18:48 2013 -0400 @@ -0,0 +1,284 @@ +# -*- 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" + +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 = @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 = @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 +# 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 + +# 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). + +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 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. + +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 + +# Expand the DEFUN family of macros + +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 +#--------------------------------------------------------------------------- + +# Which directories contain Octave source code + +INPUT = @top_srcdir@/src/ @top_srcdir@/liboctave/ +INPUT += @top_srcdir@/libcruft + +# Search subdirectories for input. + +RECURSIVE = YES + +# Our 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 +# 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 + +# Don't hide the special Doxygen comment blocks + +STRIP_CODE_COMMENTS = NO + +# 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 documentation, not source code. + +REFERENCES_LINK_SOURCE = NO + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# Generate HTML + +GENERATE_HTML = YES + +# i.e. @abs_top_builddir@/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 + +# Some of our dependency graphs are really huge... + +DOT_GRAPH_MAX_NODES = 100 \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/doxyhtml/Makefile.am Sun Jul 28 01:18:48 2013 -0400 @@ -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`
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/doxyhtml/README Sun Jul 28 01:18:48 2013 -0400 @@ -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.