Move docs in-source (#1357)

photon-docs/build.gradle

@@ -0,0 +1,294 @@
+// From allwpilib/docs. Licensed under the WPILib BSD License
+
+plugins {
+    id 'java'
+    id "org.ysb33r.doxygen" version "0.7.0"
+}
+
+
+evaluationDependsOn ':photon-targeting'
+evaluationDependsOn ':photon-core'
+evaluationDependsOn ':photon-server'
+evaluationDependsOn ':photon-lib'
+
+
+def baseArtifactIdCpp = 'documentation'
+def artifactGroupIdCpp = 'org.photonvision.cppdocs'
+def zipBaseNameCpp = '_GROUP_org.photonvision_cpp_ID_documentation_CLS'
+
+def baseArtifactIdJava = 'documentation'
+def artifactGroupIdJava = 'org.photonvision.javadocs'
+def zipBaseNameJava = '_GROUP_org.photonvision_java_ID_documentation_CLS'
+
+def outputsFolder = file("$project.buildDir/outputs")
+
+def cppProjectZips = []
+def cppIncludeRoots = []
+
+cppProjectZips.add(project(':photon-lib').cppHeadersZip)
+cppProjectZips.add(project(':photon-targeting').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 'PhotonVision C++'
+    project_logo '../wpiutil/src/main/native/resources/wpilib-128.png'
+    project_number pubVersion
+    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
+}
+
+task generateJavaDocs(type: Javadoc) {
+    def exportedProjects = [
+        ':photon-core',
+        ':photon-server',
+        ':photon-targeting',
+        ':photon-lib'
+    ]
+
+    source exportedProjects.collect { project(it).sourceSets.main.allJava }
+    classpath = files(exportedProjects.collect { project(it).sourceSets.main.compileClasspath })
+    dependsOn project(':photon-core').writeCurrentVersion
+
+    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)
+    failOnError = true
+
+    title = "PhotonVision $pubVersion"
+    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 pubVersion
+        }
+        cpp(MavenPublication) {
+            artifact zipCppDocs
+
+            artifactId = "${baseArtifactIdCpp}"
+            groupId artifactGroupIdCpp
+            version pubVersion
+        }
+    }
+
+    repositories {
+        maven {
+            // Just throw everything into build/maven
+            url(localMavenURL)
+        }
+    }
+}