Doxygen Plugin for Gradle

Table of Contents

• Requirements
• Synopsis
• Configuration
• Executables
• Which doxygen Executable?

doxygen is a popular documentation tool, especially in the C/C++ world. This plugin makes it possible to generate documentation for any of the doxygen supported languages, if such projects are built with Gradle. There is an existing doxygen extension for Ant, which already makes it possible for Gradle builds to utilise doxygen via AntBuilder, however this plugin takes a much more gradlesque approach.

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:

buildscript {
  repositories {
	jcenter()
  }
  dependencies {
    classpath 'org.ysb33r.gradle:doxygen:0.3.2'
  }
}

apply plugin : 'org.ysb33r.doxygen'

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

doxygen {
    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) {
    generate_latex false
}

Configuration

Doxygen 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 ${buildDir}/docs/doxygen.

doxygen {
  outputDir new File(buildDir,'build/docs')
}

Note	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 must be in lowercase in the configuration closure.

doxygen {
  generate_xml true
  file_patterns '*.cpp', '*.cpp'
  html_colorstyle_sat  100
}

Note	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,

Note	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

doxygen {
  executables {
    dot_path '/path/to/dot'
    hhc_location '/path/to/hhc'
  }
}

Which doxygen Executable?

By default the system path is searched for the doxygen executable. A specific path can be provided by using the executables closure

doxygen {
  executables {
     doxygen path : '/path/to/doxygen'
  }
}

As from v0.3 (for Linux, MacOSX & Windows) it is also possible to just specify the version and doxygen will be bootstrapped & cached. This means it is possible to build documentation without the build script user having to actually install doxygen !!

doxygen {
  executables {
     doxygen version : '1.8.14'
  }
}

When using the above configuration it is also possible to configure the URI where to find doxygen binaries as well as overriding where to install them.

doxygen {
  executables {
     doxygen version : '1.8.14',
        baseURI : 'ftp://our.company/binaries', // (1)
        downloadRoot : project.file('/home/shared/doxygen') // (2)
  }
}

1. Look for binaries at this URI. It will still use the default patterns as per how the doxygen project names are resolved.

2. Install the downloaded archives using this as the root directory.

For backwards compatibility with 0.2 and 0.1 it is still possible to just specify the path to the doxygen executable,

doxygen {
  executables {
    doxygen '/path/to/doxygen'
  }
}

though this will result in a deprecation warning being printed.