ax_prog_doxygen (Autoconf Archive)

ax_prog_doxygen

Synopsis

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)

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:

  doxygen-doc: Generate all doxygen documentation.

  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).

  doxygen-ps:  Generate doxygen PostScript documentation.

  doxygen-pdf: Generate doxygen PDF documentation.

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:

  $(man3_MANS): doxygen-doc

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

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

  DX_CLEANFILES = everything to clean.

Then add this variable to MOSTLYCLEANFILES.

Source Code

Download the latest version of ax_prog_doxygen.m4 or browse the macro’s revision history.

License

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.