allwpilib/docs/build.gradle

plugins {
    id 'java'
    id "org.ysb33r.doxygen" version "2.0.0"
}

evaluationDependsOn(':apriltag')
evaluationDependsOn(':cameraserver')
evaluationDependsOn(':commandsv3')
evaluationDependsOn(':cscore')
evaluationDependsOn(':epilogue-runtime')
evaluationDependsOn(':hal')
evaluationDependsOn(':ntcore')
evaluationDependsOn(':wpiannotations')
evaluationDependsOn(':commandsv2')
evaluationDependsOn(':wpilibc')
evaluationDependsOn(':wpilibj')
evaluationDependsOn(':wpimath')
evaluationDependsOn(':wpinet')
evaluationDependsOn(':wpiunits')
evaluationDependsOn(':wpiutil')
evaluationDependsOn(':romiVendordep')
evaluationDependsOn(':xrpVendordep')

def baseArtifactIdCpp = 'documentation'
def artifactGroupIdCpp = 'edu.wpi.first.wpilibc'
def zipBaseNameCpp = '_GROUP_edu_wpi_first_wpilibc_ID_documentation_CLS'

def baseArtifactIdJava = 'documentation'
def artifactGroupIdJava = 'edu.wpi.first.wpilibj'
def zipBaseNameJava = '_GROUP_edu_wpi_first_wpilibj_ID_documentation_CLS'

def outputsFolder = file("$project.buildDir/outputs")

def cppProjectZips = []
def cppIncludeRoots = []

cppProjectZips.add(project(':apriltag').cppHeadersZip)
cppProjectZips.add(project(':cameraserver').cppHeadersZip)
cppProjectZips.add(project(':cscore').cppHeadersZip)
cppProjectZips.add(project(':hal').cppHeadersZip)
cppProjectZips.add(project(':ntcore').cppHeadersZip)
cppProjectZips.add(project(':commandsv2').cppHeadersZip)
cppProjectZips.add(project(':wpilibc').cppHeadersZip)
cppProjectZips.add(project(':wpimath').cppHeadersZip)
cppProjectZips.add(project(':wpinet').cppHeadersZip)
cppProjectZips.add(project(':wpiutil').cppHeadersZip)
cppProjectZips.add(project(':romiVendordep').cppHeadersZip)
cppProjectZips.add(project(':xrpVendordep').cppHeadersZip)

doxygen {
    // Doxygen binaries are only provided for x86_64 platforms. Other platforms
    // will need to use a local Doxygen install.
    //
    // executeByVersion() fetches Doxygen binaries from
    // https://frcmaven.wpi.edu/ui/native/generic-release-mirror/doxygen/, which
    // is a mirror of binaries from https://doxygen.nl/download.html.
    //
    // Ensure theme.css (from https://github.com/jothepro/doxygen-awesome-css)
    // is compatible with Doxygen version when updating.
    executables {
        doxygen {
            // Note: has no effect if not on an x86_64 platform - you need to
            // have a global install available on your PATH for the Doxygen
            // plugin to run.
            executableByVersion('1.15.0')

            String arch = System.getProperty("os.arch");
            if (!(arch.equals("x86_64") || arch.equals("amd64"))) {
                // Search for a local Doxygen install
                executableBySearchPath('doxygen')
            }
        }
    }
}

doxygen.sourceSets.main {
    template = 'Doxyfile'

    cppProjectZips.each {
        doxygenDox.dependsOn it
        sources it.source
        it.ext.includeDirs.each {
            cppIncludeRoots.add(it.absolutePath)
        }
    }

    if (project.hasProperty('docWarningsAsErrors')) {
        // apriltag
        exclude 'apriltag_pose.h'

        // LLVM
        exclude 'wpi/Compiler.h'
        exclude 'wpi/ErrorHandling.h'
        exclude 'wpi/bit.h'
        exclude 'wpi/raw_ostream.h'
        exclude 'wpi/SmallVector.h'
        exclude 'wpi/StringExtras.h'

        // libuv
        exclude 'uv/**'

        // json
        exclude 'wpi/detail/**'

        // mpack
        exclude 'wpi/mpack.h'

        // units
        exclude 'units/**'
    }

    exclude '*.pb.h'

    // Save space by excluding eigen
    exclude 'Eigen/**'
    exclude 'unsupported/**'

    exclude '**/.clang-tidy'
    exclude '**/.clang-format'

    option 'project_name', 'WPILibC++'
    option 'project_logo', '../wpiutil/src/main/native/resources/wpilib-128.png'
    option 'project_number', wpilibVersioning.version.get()
    option 'strip_from_inc_path', cppIncludeRoots
    option 'strip_from_path', cppIncludeRoots

    if (project.hasProperty('docWarningsAsErrors')) {
        option 'warn_as_error', 'FAIL_ON_WARNINGS_PRINT'
    }
}

tasks.register("zipCppDocs", Zip) {
    archiveBaseName = zipBaseNameCpp
    archiveVersion = ""
    destinationDirectory = outputsFolder
    dependsOn doxygenDox
    from ("$buildDir/docs/doxygen/html")
    into '/'
}

// Java
configurations {
    javaSource {
        transitive = false
    }
}

task generateJavaDocs(type: Javadoc) {
    classpath += project(":wpilibj").sourceSets.main.compileClasspath
    options.links("https://docs.oracle.com/en/java/javase/21/docs/api/")
    options.links("https://docs.opencv.org/4.x/javadoc/")
    options.addStringOption("tag", "pre:a:Pre-Condition")
    options.addBooleanOption("Xdoclint/package:" +
            // TODO: v Document these, then remove them from the list
            "-edu.wpi.first.hal," +
            "-edu.wpi.first.hal.simulation," +
            // TODO: ^ Document these, then remove them from the list
            "-edu.wpi.first.math.proto," +
            "-edu.wpi.first.math.struct," +
            "-edu.wpi.first.math.controller.proto," +
            "-edu.wpi.first.math.controller.struct," +
            "-edu.wpi.first.math.geometry.proto," +
            "-edu.wpi.first.math.geometry.struct," +
            "-edu.wpi.first.math.kinematics.proto," +
            "-edu.wpi.first.math.kinematics.struct," +
            "-edu.wpi.first.math.spline.proto," +
            "-edu.wpi.first.math.spline.struct," +
            "-edu.wpi.first.math.system.proto," +
            "-edu.wpi.first.math.system.struct," +
            "-edu.wpi.first.math.system.plant.proto," +
            "-edu.wpi.first.math.system.plant.struct," +
            "-edu.wpi.first.math.trajectory.proto," +
            "-edu.wpi.first.math.trajectory.struct," +
            "-org.wpilib.commands3.proto," +
            // The .measure package contains generated source files for which automatic javadoc
            // generation is very difficult to do meaningfully.
            "-edu.wpi.first.units.measure", true)
    options.addBooleanOption("Xdoclint:html,missing,reference,syntax", true)
    options.addBooleanOption('html5', true)
    options.linkSource(true)
    dependsOn project(':wpilibj').generateJavaVersion
    source project(':apriltag').sourceSets.main.java
    source project(':cameraserver').sourceSets.main.java
    source project(':commandsv3').sourceSets.main.java
    source project(':cscore').sourceSets.main.java
    source project(':epilogue-runtime').sourceSets.main.java
    source project(':hal').sourceSets.main.java
    source project(':ntcore').sourceSets.main.java
    source project(':wpiannotations').sourceSets.main.java
    source project(':commandsv2').sourceSets.main.java
    source project(':wpilibj').sourceSets.main.java
    source project(':wpimath').sourceSets.main.java
    source project(':wpinet').sourceSets.main.java
    source project(':wpiunits').sourceSets.main.java
    source project(':wpiutil').sourceSets.main.java
    source project(':romiVendordep').sourceSets.main.java
    source project(':xrpVendordep').sourceSets.main.java
    source configurations.javaSource.collect { zipTree(it) }
    include '**/*.java'
    failOnError = true

    title = "WPILib API ${wpilibVersioning.version.get()}"
    ext.entryPoint = "$destinationDir/index.html"

    if (JavaVersion.current().isJava8Compatible() && project.hasProperty('docWarningsAsErrors')) {
        // Treat javadoc warnings as errors.
        //
        // The second argument '-quiet' is a hack. The one parameter
        // addStringOption() doesn't work, so we add '-quiet', which is added
        // anyway by gradle. See https://github.com/gradle/gradle/issues/2354.
        options.addStringOption('Werror', '-quiet')
    }
}

tasks.register("zipJavaDocs", Zip) {
    archiveBaseName = zipBaseNameJava
    archiveVersion = ""
    destinationDirectory = outputsFolder
    dependsOn generateJavaDocs
    from ("$buildDir/docs/javadoc")
    into '/'
}

tasks.register("zipDocs") {
    dependsOn zipCppDocs
    dependsOn zipJavaDocs
}

apply plugin: 'maven-publish'

publishing {
    publications {
        java(MavenPublication) {
            artifact zipJavaDocs

            artifactId = "${baseArtifactIdJava}"
            groupId = artifactGroupIdJava
            version = wpilibVersioning.version.get()
        }
        cpp(MavenPublication) {
            artifact zipCppDocs

            artifactId = "${baseArtifactIdCpp}"
            groupId = artifactGroupIdCpp
            version = wpilibVersioning.version.get()
        }
    }
}