@node ax_prog_doxygen
@unnumberedsec ax_prog_doxygen

@majorheading Synopsis

@smallexample
DX_INIT_DOXYGEN(PROJECT-NAME, [DOXYFILE-PATH], [OUTPUT-DIR], ...)
DX_DOXYGEN_FEATURE(ON|OFF)
DX_DOT_FEATURE(ON|OFF)
DX_HTML_FEATURE(ON|OFF)
DX_CHM_FEATURE(ON|OFF)
DX_CHI_FEATURE(ON|OFF)
DX_MAN_FEATURE(ON|OFF)
DX_RTF_FEATURE(ON|OFF)
DX_XML_FEATURE(ON|OFF)
DX_PDF_FEATURE(ON|OFF)
DX_PS_FEATURE(ON|OFF)
@end smallexample

@majorheading Description

The DX_*_FEATURE macros control the default setting for the given
Doxygen feature. Supported features are 'DOXYGEN' itself, 'DOT' for
generating graphics, 'HTML' for plain HTML, 'CHM' for compressed HTML
help (for MS users), 'CHI' for generating a separate .chi file by the
.chm file, and 'MAN', 'RTF', 'XML', 'PDF' and 'PS' for the appropriate
output formats. The environment variable DOXYGEN_PAPER_SIZE may be
specified to override the default 'a4wide' paper size.

By default, HTML, PDF and PS documentation is generated as this seems to
be the most popular and portable combination. MAN pages created by
Doxygen are usually problematic, though by picking an appropriate subset
and doing some massaging they might be better than nothing. CHM and RTF
are specific for MS (note that you can't generate both HTML and CHM at
the same time). The XML is rather useless unless you apply specialized
post-processing to it.

The macros mainly control the default state of the feature. The use can
override the default by specifying --enable or --disable. The macros
ensure that contradictory flags are not given (e.g.,
--enable-doxygen-html and --enable-doxygen-chm,
--enable-doxygen-anything with --disable-doxygen, etc.) Finally, each
feature will be automatically disabled (with a warning) if the required
programs are missing.

Once all the feature defaults have been specified, call DX_INIT_DOXYGEN
with the following parameters: a one-word name for the project for use
as a filename base etc., an optional configuration file name (the
default is '$(srcdir)/Doxyfile', the same as Doxygen's default), and an
optional output directory name (the default is 'doxygen-doc'). To run
doxygen multiple times for different configuration files and output
directories provide more parameters: the second, forth, sixth, etc
parameter are configuration file names and the third, fifth, seventh,
etc parameter are output directories. No checking is done to catch
duplicates.

Automake Support

The DX_RULES substitution can be used to add all needed rules to the
Makefile. Note that this is a substitution without being a variable:
only the @@DX_RULES@@ syntax will work.

The provided targets are:

@smallexample
  doxygen-doc: Generate all doxygen documentation.
@end smallexample

@smallexample
  doxygen-run: Run doxygen, which will generate some of the
               documentation (HTML, CHM, CHI, MAN, RTF, XML)
               but will not do the post processing required
               for the rest of it (PS, PDF).
@end smallexample

@smallexample
  doxygen-ps:  Generate doxygen PostScript documentation.
@end smallexample

@smallexample
  doxygen-pdf: Generate doxygen PDF documentation.
@end smallexample

Note that by default these are not integrated into the automake targets.
If doxygen is used to generate man pages, you can achieve this
integration by setting man3_MANS to the list of man pages generated and
then adding the dependency:

@smallexample
  $(man3_MANS): doxygen-doc
@end smallexample

This will cause make to run doxygen and generate all the documentation.

The following variable is intended for use in Makefile.am:

@smallexample
  DX_CLEANFILES = everything to clean.
@end smallexample

Then add this variable to MOSTLYCLEANFILES.

@majorheading Source Code

Download the
@uref{http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_prog_doxygen.m4,latest
version of @file{ax_prog_doxygen.m4}} or browse
@uref{http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=history;f=m4/ax_prog_doxygen.m4,the
macro's revision history}.

@majorheading License

@w{Copyright @copyright{} 2009 Oren Ben-Kiki @email{oren@@ben-kiki.org}} @* @w{Copyright @copyright{} 2015 Olaf Mandel @email{olaf@@mandel.name}}

Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice
and this notice are preserved. This file is offered as-is, without any
warranty.