allwpilib/docs/build.gradle

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

evaluationDependsOn(':apriltag')
evaluationDependsOn(':cameraserver')
evaluationDependsOn(':cscore')
evaluationDependsOn(':hal')
evaluationDependsOn(':ntcore')
evaluationDependsOn(':wpilibNewCommands')
evaluationDependsOn(':wpilibc')
evaluationDependsOn(':wpilibj')
evaluationDependsOn(':wpimath')
evaluationDependsOn(':wpinet')
evaluationDependsOn(':wpiunits')
evaluationDependsOn(':wpiutil')

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(':wpilibNewCommands').cppHeadersZip)
cppProjectZips.add(project(':wpilibc').cppHeadersZip)
cppProjectZips.add(project(':wpimath').cppHeadersZip)
cppProjectZips.add(project(':wpinet').cppHeadersZip)
cppProjectZips.add(project(':wpiutil').cppHeadersZip)

doxygen {
    // Doxygen binaries are only provided for x86_64 platforms
    // Other platforms will need to provide doxygen via their system
    // See below maven and https://doxygen.nl/download.html for provided binaries

    String arch = System.getProperty("os.arch");
    if (arch.equals("x86_64") || arch.equals("amd64")) {
        executables {
            doxygen version : '1.9.4',
            baseURI : 'https://frcmaven.wpi.edu/artifactory/generic-release-mirror/doxygen'
        }
    }
}

doxygen {
    generate_html true
    html_extra_stylesheet 'theme.css'

    cppProjectZips.each {
        dependsOn it
        source it.source
        it.ext.includeDirs.each {
            cppIncludeRoots.add(it.absolutePath)
        }
    }
    cppIncludeRoots << '../ntcore/build/generated/main/native/include/'

    if (project.hasProperty('docWarningsAsErrors')) {
        // Eigen
        exclude 'Eigen/**'
        exclude 'unsupported/**'

        // LLVM
        exclude 'wpi/AlignOf.h'
        exclude 'wpi/Casting.h'
        exclude 'wpi/Chrono.h'
        exclude 'wpi/Compiler.h'
        exclude 'wpi/ConvertUTF.h'
        exclude 'wpi/DenseMap.h'
        exclude 'wpi/DenseMapInfo.h'
        exclude 'wpi/Endian.h'
        exclude 'wpi/EpochTracker.h'
        exclude 'wpi/Errc.h'
        exclude 'wpi/Errno.h'
        exclude 'wpi/ErrorHandling.h'
        exclude 'wpi/bit.h'
        exclude 'wpi/fs.h'
        exclude 'wpi/FunctionExtras.h'
        exclude 'wpi/function_ref.h'
        exclude 'wpi/Hashing.h'
        exclude 'wpi/iterator.h'
        exclude 'wpi/iterator_range.h'
        exclude 'wpi/ManagedStatic.h'
        exclude 'wpi/MapVector.h'
        exclude 'wpi/MathExtras.h'
        exclude 'wpi/MemAlloc.h'
        exclude 'wpi/PointerIntPair.h'
        exclude 'wpi/PointerLikeTypeTraits.h'
        exclude 'wpi/PointerUnion.h'
        exclude 'wpi/raw_os_ostream.h'
        exclude 'wpi/raw_ostream.h'
        exclude 'wpi/SmallPtrSet.h'
        exclude 'wpi/SmallSet.h'
        exclude 'wpi/SmallString.h'
        exclude 'wpi/SmallVector.h'
        exclude 'wpi/StringExtras.h'
        exclude 'wpi/StringMap.h'
        exclude 'wpi/SwapByteOrder.h'
        exclude 'wpi/type_traits.h'
        exclude 'wpi/VersionTuple.h'
        exclude 'wpi/WindowsError.h'

        // fmtlib
        exclude 'fmt/**'

        // libuv
        exclude 'uv.h'
        exclude 'uv/**'
        exclude 'wpinet/uv/**'

        // json
        exclude 'wpi/adl_serializer.h'
        exclude 'wpi/byte_container_with_subtype.h'
        exclude 'wpi/detail/**'
        exclude 'wpi/json.h'
        exclude 'wpi/json_fwd.h'
        exclude 'wpi/ordered_map.h'
        exclude 'wpi/thirdparty/**'

        // memory
        exclude 'wpi/memory/**'

        // mpack
        exclude 'wpi/mpack.h'

        // units
        exclude 'units/**'
    }

    //TODO: building memory docs causes search to break
    exclude 'wpi/memory/**'

    exclude '*.pb.h'

    // Save space by excluding protobuf and eigen
    exclude 'Eigen/**'
    exclude 'google/protobuf/**'

    aliases 'effects=\\par <i>Effects:</i>^^',
            'notes=\\par <i>Notes:</i>^^',
            'requires=\\par <i>Requires:</i>^^',
            'requiredbe=\\par <i>Required Behavior:</i>^^',
            'concept{2}=<a href=\"md_doc_concepts.html#\1\">\2</a>',
            'defaultbe=\\par <i>Default Behavior:</i>^^'
    case_sense_names false
    extension_mapping 'inc=C++', 'no_extension=C++'
    extract_all true
    extract_static true
    file_patterns '*'
    full_path_names true
    generate_html true
    generate_latex false
    generate_treeview true
    html_extra_stylesheet 'theme.css'
    html_timestamp true
    javadoc_autobrief true
    project_name 'WPILibC++'
    project_logo '../wpiutil/src/main/native/resources/wpilib-128.png'
    project_number wpilibVersioning.version.get()
    quiet true
    recursive true
    strip_code_comments false
    strip_from_inc_path cppIncludeRoots as String[]
    strip_from_path cppIncludeRoots as String[]
    use_mathjax true
    warnings false
    warn_if_incomplete_doc true
    warn_if_undocumented false
    warn_no_paramdoc true

    //enable doxygen preprocessor expansion of WPI_DEPRECATED to fix MotorController docs
    enable_preprocessing true
    macro_expansion true
    expand_only_predef true
    predefined "WPI_DEPRECATED(x)=[[deprecated(x)]]\"\\\n" +
            "\"__cplusplus\"\\\n" +
            "\"HAL_ENUM(name)=enum name : int32_t"

    if (project.hasProperty('docWarningsAsErrors')) {
        warn_as_error 'FAIL_ON_WARNINGS'
    }
}

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

// Java
configurations {
    javaSource {
        transitive false
    }
}

ext {
    sharedCvConfigs = [:]
    staticCvConfigs = [:]
    useJava = true
    useCpp = false
    skipDev = true
    useDocumentation = true
}

apply from: "${rootDir}/shared/opencv.gradle"

task generateJavaDocs(type: Javadoc) {
    classpath += project(":wpimath").sourceSets.main.compileClasspath
    options.links("https://docs.oracle.com/en/java/javase/17/docs/api/")
    options.addStringOption("tag", "pre:a:Pre-Condition")
    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(':cscore').sourceSets.main.java
    source project(':hal').sourceSets.main.java
    source project(':ntcore').sourceSets.main.java
    source project(':wpilibNewCommands').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 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.
        //
        // See JDK-8200363 (https://bugs.openjdk.java.net/browse/JDK-8200363)
        // for information about the nonstandard -Xwerror option. JDK 15+ has
        // -Werror.
        options.addStringOption('Xwerror', '-quiet')
    }

    if (JavaVersion.current().isJava11Compatible()) {
        if (!JavaVersion.current().isJava12Compatible()) {
            options.addBooleanOption('-no-module-directories', true)
        }
        doLast {
            // This is a work-around for https://bugs.openjdk.java.net/browse/JDK-8211194. Can be removed once that issue is fixed on JDK's side
            // Since JDK 11, package-list is missing from javadoc output files and superseded by element-list file, but a lot of external tools still need it
            // Here we generate this file manually
            new File(destinationDir, 'package-list').text = new File(destinationDir, 'element-list').text
        }
    }
}

tasks.register("zipJavaDocs", Zip) {
    archiveBaseName = zipBaseNameJava
    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()
        }
    }
}