Doxygen 1.0.4

Requirements

The plugin currently requires that the doxygen(.exe) native binary is available. Any other optional binaries that are called such as dot also need to be installed if they are required as part of the documentation build process. By default Gradle will use the search path to find these binaries, but it is possible to explicitly define their locations if necessary,

Synopsis

To bootstrap the plugin and for the latest released version see https://plugins.gradle.org/plugin/org.ysb33r.doxygen

This will create a default task called doxygen which can be configured.

doxygen {
    option 'generate_html', true

    source new File(projectDir,'src/main/cpp')
    source new File(projectDir,'src/main/headers')
}

It is also possible to define a custom doxygen tasks

import org.ysb33r.gradle.doxygen.Doxygen

task myAwesomeDoxygenTask (type:Doxygen) {
    options generate_latex:  false
}

Configuration

DoxygenTask is a SourceTask and all appropriate operations can be used.

doxygen {
  source 'src/main/cpp'
  exclude 'foo.cpp'
}

A pre-configured Doxyfile template can be supplied. At build-time this template will be copied and appropriate values supplied via the configuration closure will be substituted. This is done via the template parameter.

doxygen {
  template 'src/main/dox/myDoxyfileTemplate'
}

If no template is supplied, the build process will call doxygen -g to generate a default template.

The output directory is set via outputDir. The default output directory, if not supplied, is build/docs/doxygen.

doxygen {
  outputDir new File(buildDir,'build/docs')
}
output_directory is an alias for outputDir.

Most Doxyfile properties can be used in the configuration closure. By convention all Doxyfile properties are in uppercase, but to keep it gradlesque, they can be in lowercase in the configuration closure.

doxygen {
 option 'generate_xml', true (1)
  options html_colorstyle_sat : 100, (2)
        file_patterns: ['*.cpp', '*.cpp'] (3)

}
1 Set a single option
2 Set multiple options using map-style. (Kotlin DSL users should use mapOf instead)
3 Lists must be explicitely specified.
Multiple items in a Doxyfile are space separated, but in the configuration script they are specified comma-separated, just like any other list. The plugin will take care of the translation and also to quote any items that may contain spaces,
Any property that is boolean should be set using true or false.

Certain Doxyfile properties which are treated differently:

  • DOT_PATH - Use executables closure instead

  • HHC_LOCATION - Use executables closure instead

  • IMAGE_PATHS - Use image_paths instead and the plugin will take care of ensuring files and directories are part of the dependencies of the task

  • INPUT - Use source and sourceDir instead.

  • MSCGEN_PATH - Use executables closure instead

  • PERL_PATH - Use executables closure instead

  • PROJECT_NAME - project.name will be used as the default value. If you want to override use project_name

  • PROJECT_NUMBER - project.version will be used as the default value. If you want to override use project_number

Executables

Executables are configured via a special closure or Action.

doxygen {
  executables {
    doxygen {
       executableByVersion('7.0.1') (1)
       executableByPath('/path/to/doxygen') (2)
       executableBySearchPath('doxygen') (3)
    }
    dot {
       enabled = true (4)
       executableByVersion('7.0.1') (5)
       executableByPath('/path/to/dot') (6)
       executableBySearchPath('dot') (7)
    }
    perl {
       enabled = true (8)
       executableByPath('/path/to/perl') (9)
       executableBySearchPath('perl') (10)
    }
    hhc {
       enabled = true (11)
       executableByPath('/path/to/chm.exe') (12)
       executableBySearchPath('chm') (13)
    }
    mscgen {
       nabled = true (14)
       executableByVersion('0.20') (15)
       executableByPath('/path/to/doxygen') (16)
       executableBySearchPath('doxygen') (17)
    }
  }
}
1 Download and use a version of doxygen. This is the default for Windows, Linux & Mac OSX. You can override the base URI where to download from by setting a system property or Gradle Property org.ysb33r.gradle.doxygen.download.url. You can also set an environmental variable ORG_YSB33R_GRADLE_DOXYGEN_DOWNLOAD_URL.
2 Set an explicit path to doxygen
3 Search for doxygen in the system search path. This is the default for anything else.
4 dot is disabled be default. Enable it if you need Graphviz-based diagrams.
5 Download and use a version of dot. This is currently only supported on Windows. On this platform it will use a predefined version, but you can choose to override that if necessary. You can override the base URI where to download from by setting a system property or Gradle Property org.ysb33r.gradle.dot.download.url. You can also set an environmental variable ORG_YSB33R_GRADLE_DOT_DOWNLOAD_URL.
6 Provide an explicit path to dot.
7 Look for dot in the system search path. This is the default for anything non-Windows.
8 Perl is disabled be default. Enable it if you need Perl as part of your documentation build.
9 Provide an explicit path to Perl.
10 Search for perl in the system search path. This is the default behaviour whehn Perl is enabled.
11 Windows Help Compiler is disabled be default. Enable it if you need it as part of your documentation build.
12 Provide an explicit path to chm.exe.
13 Search for chm in the system search path. This is the default behaviour HHC-usage is enabled.
14 mscgen is disabled be default. Enable it if you need it for diagrams.
15 Download and use a version of mscgen. This is the default behaviour on Windows & Linux. You can override the base URI where to download from by setting a system property or Gradle Property org.ysb33r.gradle.mscgen.download.url. You can also set an environmental variable ORG_YSB33R_GRADLE_MSCGEN_DOWNLOAD_URL.
16 Provide an explicit path to mscgen.
17 Search for mscgen in the system search path. This is the default behaviour when not Windows or Linux X86.

Contributors

A thank you goes to the following contributors, which are not project members