Publish API docs (#1094)

Redirects I want eventually ( @Bankst )

demo.photonvision.org redirected to https://photonvision.github.io/photonvision/built-client/
javadocs.photonvision.org redirected to https://photonvision.github.io/photonvision/built-docs/javadoc/
cppdocs.photonvision.org redirected to https://photonvision.github.io/photonvision/built-docs/doxygen/html/

For now this runs on all commits to master. Once we confirm it works, let's pull back to only tagged releases


---------

Co-authored-by: Mohammad Durrani <46766905+mdurrani808@users.noreply.github.com>
Co-authored-by: Chris <chrisgerth010592@gmail.com>

.github/workflows/build.yml

@@ -81,7 +81,7 @@ jobs:
       - name: Gradle Build
         run: |
           chmod +x gradlew
-          ./gradlew photon-server:build photon-lib:build -x check --max-workers 2
+          ./gradlew build -x check --max-workers 2
       - name: Gradle Tests
         run: ./gradlew testHeadless -i --max-workers 1 --stacktrace
       - name: Gradle Coverage

.github/workflows/documentation.yml

@@ -0,0 +1,92 @@
+name: Documentation
+
+on:
+  push:
+    # For now, run on all commits to master
+    branches: [ master ]
+    # and also all tags starting with v
+    tags:
+      - 'v*'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-client:
+    name: "PhotonClient Build"
+    defaults:
+      run:
+        working-directory: photon-client
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - name: Install Dependencies
+        run: npm ci
+      - name: Build Production Client
+        run: npm run build-demo
+      - uses: actions/upload-artifact@v4
+        with:
+          name: built-client
+          path: photon-client/dist/
+
+  run_docs:
+    runs-on: "ubuntu-22.04"
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Fetch tags
+      run: git fetch --tags --force
+    - name: Install Java 17
+      uses: actions/setup-java@v3
+      with:
+        java-version: 17
+        distribution: temurin
+
+    - name: Build javadocs/doxygen
+      run: |
+        chmod +x gradlew
+        ./gradlew docs:generateJavaDocs docs:doxygen
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: built-docs
+        path: docs/build/docs
+
+  release:
+    needs: [build-client, run_docs]
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-22.04
+    steps:
+
+      # Download literally every single artifact.
+      - uses: actions/download-artifact@v4
+
+      - run: find .
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: '.'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -92,3 +92,10 @@ Our meeting notes can be found in the wiki section of this repository.
 
 * [2020 Meeting Notes](https://github.com/PhotonVision/photonvision/wiki/2020-Meeting-Notes)
 * [2021 Meeting Notes](https://github.com/PhotonVision/photonvision/wiki/2021-Meeting-Notes)
+
+## Documentation
+
+- Our main documentation page: [docs.photonvision.org](https://docs.photonvision.org)
+- Photon UI demo: [demo.photonvision.org](https://demo.photonvision.org) (or [manual link](https://photonvision.github.io/photonvision/built-client/))
+- Javadocs: [javadocs.photonvision.org](https://javadocs.photonvision.org) (or [manual link](https://photonvision.github.io/photonvision/built-docs/javadoc/))
+- C++ Doxygen  [cppdocs.photonvision.org](https://cppdocs.photonvision.org) (or [manual link](https://photonvision.github.io/photonvision/built-docs/doxygen/html/))

docs/build.gradle

@@ -0,0 +1,287 @@
+// 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.wpilibc'
+def zipBaseNameCpp = '_GROUP_org.photonvision_cpp_ID_documentation_CLS'
+
+def baseArtifactIdJava = 'documentation'
+def artifactGroupIdJava = 'org.photonvision.wpilibj'
+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
+        }
+    }
+}

photon-client/package.json

@@ -7,6 +7,7 @@
     "build": "run-p build-only",
     "preview": "vite preview --port 4173",
     "build-only": "vite build",
+    "build-demo": "vite build --mode demo",
     "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",
     "format": "prettier --write src/",
     "lint-ci": "eslint . --max-warnings 0 --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",

photon-client/src/App.vue

@@ -8,43 +8,45 @@ import PhotonSidebar from "@/components/app/photon-sidebar.vue";
 import PhotonLogView from "@/components/app/photon-log-view.vue";
 import PhotonErrorSnackbar from "@/components/app/photon-error-snackbar.vue";
 
-const websocket = new AutoReconnectingWebsocket(
-  `ws://${inject("backendHost")}/websocket_data`,
-  () => {
-    useStateStore().$patch({ backendConnected: true });
-  },
-  (data) => {
-    if (data.log !== undefined) {
-      useStateStore().addLogFromWebsocket(data.log);
+const is_demo = import.meta.env.MODE === "demo";
+if (!is_demo) {
+  const websocket = new AutoReconnectingWebsocket(
+    `ws://${inject("backendHost")}/websocket_data`,
+    () => {
+      useStateStore().$patch({ backendConnected: true });
+    },
+    (data) => {
+      if (data.log !== undefined) {
+        useStateStore().addLogFromWebsocket(data.log);
+      }
+      if (data.settings !== undefined) {
+        useSettingsStore().updateGeneralSettingsFromWebsocket(data.settings);
+      }
+      if (data.cameraSettings !== undefined) {
+        useCameraSettingsStore().updateCameraSettingsFromWebsocket(data.cameraSettings);
+      }
+      if (data.ntConnectionInfo !== undefined) {
+        useStateStore().updateNTConnectionStatusFromWebsocket(data.ntConnectionInfo);
+      }
+      if (data.metrics !== undefined) {
+        useSettingsStore().updateMetricsFromWebsocket(data.metrics);
+      }
+      if (data.updatePipelineResult !== undefined) {
+        useStateStore().updateBackendResultsFromWebsocket(data.updatePipelineResult);
+      }
+      if (data.mutatePipelineSettings !== undefined && data.cameraIndex !== undefined) {
+        useCameraSettingsStore().changePipelineSettingsInStore(data.mutatePipelineSettings, data.cameraIndex);
+      }
+      if (data.calibrationData !== undefined) {
+        useStateStore().updateCalibrationStateValuesFromWebsocket(data.calibrationData);
+      }
+    },
+    () => {
+      useStateStore().$patch({ backendConnected: false });
     }
-    if (data.settings !== undefined) {
-      useSettingsStore().updateGeneralSettingsFromWebsocket(data.settings);
-    }
-    if (data.cameraSettings !== undefined) {
-      useCameraSettingsStore().updateCameraSettingsFromWebsocket(data.cameraSettings);
-    }
-    if (data.ntConnectionInfo !== undefined) {
-      useStateStore().updateNTConnectionStatusFromWebsocket(data.ntConnectionInfo);
-    }
-    if (data.metrics !== undefined) {
-      useSettingsStore().updateMetricsFromWebsocket(data.metrics);
-    }
-    if (data.updatePipelineResult !== undefined) {
-      useStateStore().updateBackendResultsFromWebsocket(data.updatePipelineResult);
-    }
-    if (data.mutatePipelineSettings !== undefined && data.cameraIndex !== undefined) {
-      useCameraSettingsStore().changePipelineSettingsInStore(data.mutatePipelineSettings, data.cameraIndex);
-    }
-    if (data.calibrationData !== undefined) {
-      useStateStore().updateCalibrationStateValuesFromWebsocket(data.calibrationData);
-    }
-  },
-  () => {
-    useStateStore().$patch({ backendConnected: false });
-  }
-);
-
-useStateStore().$patch({ websocket: websocket });
+  );
+  useStateStore().$patch({ websocket: websocket });
+}
 </script>
 
 <template>

photon-core/src/main/java/org/photonvision/vision/camera/CameraInfo.java

@@ -62,7 +62,6 @@ public class CameraInfo extends UsbCameraInfo {
     }
 
     /**
-     * @param baseName
      * @return Returns a human readable name
      */
     public String getHumanReadableName() {

photon-core/src/main/java/org/photonvision/vision/pipe/impl/ArucoDetectionPipeParams.java

@@ -33,7 +33,7 @@ public class ArucoDetectionPipeParams {
     /**
      * Bits allowed to be corrected, expressed as a ratio of the tag families theoretical maximum.
      *
-     * <p>E.g. 36h11 -> 11 * errorCorrectionRate = Max error bits
+     * <p>E.g. 36h11 = 11 * errorCorrectionRate = Max error bits
      */
     public double errorCorrectionRate = 0;
 

settings.gradle

@@ -2,3 +2,4 @@ include 'photon-targeting'
 include 'photon-core'
 include 'photon-server'
 include 'photon-lib'
+include 'docs'

shared/common.gradle

@@ -74,6 +74,34 @@ tasks.register('generateJavaDocs', Javadoc) {
     source = sourceSets.main.allJava
     classpath = sourceSets.main.compileClasspath
     destinationDir = file("${projectDir}/build/docs")
+
+    options.addBooleanOption("Xdoclint:html,missing,reference,syntax", true)
+    options.addBooleanOption('html5', true)
+
+    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
+        }
+    }
 }
 
 jacoco {