[ci] Consolidate docs jobs (#7910)

We build docs in three different places, which is annoying to deal with, and it means we build docs two more times than necessary. Now, docs are built just once in the main Gradle workflow, with warnings promoted to errors, eliminating the need for the separate job in lint-format.yml. The uploaded docs artifact is then unpacked and commited to the GitHub Pages repo like normal.

.github/workflows/documentation.yml

@@ -1,67 +0,0 @@
-name: Documentation
-
-on: [push, workflow_dispatch]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-env:
-  BASE_PATH: allwpilib/docs
-
-jobs:
-  publish:
-    name: "Documentation - Publish"
-    runs-on: ubuntu-22.04
-    if: github.repository == 'wpilibsuite/allwpilib' && (github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '2027')))
-    concurrency: ci-docs-publish
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-      - uses: gradle/actions/wrapper-validation@v4
-      - uses: actions/setup-java@v4
-        with:
-          distribution: 'temurin'
-          java-version: 17
-      - name: Set environment variables (Development)
-        run: |
-          echo "BRANCH=development" >> $GITHUB_ENV
-        if: github.ref == 'refs/heads/main'
-      - name: Set environment variables (Tag)
-        run: |
-          echo "EXTRA_GRADLE_ARGS=-PreleaseMode" >> $GITHUB_ENV
-          echo "BRANCH=beta" >> $GITHUB_ENV
-        if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '2027')
-      - name: Set environment variables (Release)
-        run: |
-          echo "EXTRA_GRADLE_ARGS=-PreleaseMode" >> $GITHUB_ENV
-          echo "BRANCH=release" >> $GITHUB_ENV
-        if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, 'alpha') && !contains(github.ref, 'beta') && !contains(github.ref, '2027')
-      - name: Build with Gradle
-        run: ./gradlew docs:generateJavaDocs docs:doxygen -PbuildServer ${{ env.EXTRA_GRADLE_ARGS }}
-      - name: Install SSH Client 🔑
-        uses: webfactory/ssh-agent@v0.9.0
-        with:
-          ssh-private-key: ${{ secrets.GH_DEPLOY_KEY }}
-      - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@v4.6.1
-        with:
-          ssh-key: true
-          repository-name: wpilibsuite/wpilibsuite.github.io
-          branch: allwpilib-${{ env.BRANCH }}
-          clean: true
-          single-commit: true
-          folder: docs/build/docs
-      - name: Trigger Workflow
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ secrets.DISPATCH_PAT_TOKEN }}
-          script: |
-            github.rest.actions.createWorkflowDispatch({
-              owner: context.repo.owner,
-              repo: 'wpilibsuite.github.io',
-              workflow_id: 'static.yml',
-              ref: 'main',
-            })

.github/workflows/gradle.yml

@@ -203,7 +203,7 @@ jobs:
         run: echo "EXTRA_GRADLE_ARGS=-PreleaseMode" >> $GITHUB_ENV
         if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '2027')
       - name: Build with Gradle
-        run: ./gradlew docs:zipDocs --build-cache -PbuildServer ${{ env.EXTRA_GRADLE_ARGS }}
+        run: ./gradlew docs:zipDocs --build-cache -PbuildServer -PdocWarningsAsErrors ${{ env.EXTRA_GRADLE_ARGS }}
         env:
           ARTIFACTORY_PUBLISH_USERNAME: ${{ secrets.ARTIFACTORY_USERNAME }}
           ARTIFACTORY_PUBLISH_PASSWORD: ${{ secrets.ARTIFACTORY_PASSWORD }}
@@ -212,6 +212,68 @@ jobs:
           name: Documentation
           path: docs/build/outputs
 
+  publish:
+    name: "Documentation - Publish"
+    runs-on: ubuntu-22.04
+    if: github.repository == 'wpilibsuite/allwpilib' && (github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '2027')))
+    needs: [build-documentation]
+    concurrency: ci-docs-publish
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Download docs artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: Documentation
+      - name: Make output directories
+        run: |
+          mkdir -p docs/tmp/doxygen/html
+          mkdir -p docs/tmp/javadoc
+      - name: Extract docs
+        run: |
+          unzip _GROUP_edu_wpi_first_wpilibc_ID_documentation_CLS.zip -d docs/tmp/doxygen/html
+          unzip _GROUP_edu_wpi_first_wpilibj_ID_documentation_CLS.zip -d docs/tmp/javadoc
+      - name: Set environment variables (Development)
+        run: |
+          echo "BRANCH=development" >> $GITHUB_ENV
+        if: github.ref == 'refs/heads/main'
+      - name: Set environment variables (Tag)
+        run: |
+          echo "EXTRA_GRADLE_ARGS=-PreleaseMode" >> $GITHUB_ENV
+          echo "BRANCH=beta" >> $GITHUB_ENV
+        if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '2027')
+      - name: Set environment variables (Release)
+        run: |
+          echo "EXTRA_GRADLE_ARGS=-PreleaseMode" >> $GITHUB_ENV
+          echo "BRANCH=release" >> $GITHUB_ENV
+        if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, 'alpha') && !contains(github.ref, 'beta') && !contains(github.ref, '2027')
+      - name: Install SSH Client 🔑
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.GH_DEPLOY_KEY }}
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4.6.1
+        with:
+          ssh-key: true
+          repository-name: wpilibsuite/wpilibsuite.github.io
+          branch: allwpilib-${{ env.BRANCH }}
+          clean: true
+          single-commit: true
+          folder: docs/tmp
+      - name: Trigger Workflow
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.DISPATCH_PAT_TOKEN }}
+          script: |
+            github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: 'wpilibsuite.github.io',
+              workflow_id: 'static.yml',
+              ref: 'main',
+            })
+
   combine:
     name: Combine
     needs: [build-docker, build-host, build-documentation]

.github/workflows/lint-format.yml

@@ -123,18 +123,3 @@ jobs:
           echo '' >> $GITHUB_STEP_SUMMARY
           echo '```' >> $GITHUB_STEP_SUMMARY
         if: ${{ failure() }}
-
-  documentation:
-    name: "Documentation"
-    runs-on: ubuntu-22.04
-    needs: [validation]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-java@v4
-        with:
-          distribution: 'temurin'
-          java-version: 21
-      - name: Build with Gradle
-        run: ./gradlew docs:zipDocs -PbuildServer -PdocWarningsAsErrors ${{ env.EXTRA_GRADLE_ARGS }}

docs/build.gradle

@@ -77,66 +77,19 @@ doxygen.sourceSets.main {
         // apriltag
         exclude 'apriltag_pose.h'
 
-        // 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/**'
 
         // mpack
         exclude 'wpi/mpack.h'

upstream_utils/json_patches/0001-Remove-version-from-namespace.patch

@@ -1,7 +1,7 @@
 From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
 From: Tyler Veness <calcmogul@gmail.com>
 Date: Fri, 8 Sep 2023 19:21:41 -0700
-Subject: [PATCH 1/4] Remove version from namespace
+Subject: [PATCH 1/5] Remove version from namespace
 
 ---
  include/nlohmann/detail/abi_macros.hpp | 45 ++------------------------

upstream_utils/json_patches/0002-Make-serializer-public.patch

@@ -1,7 +1,7 @@
 From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
 From: Tyler Veness <calcmogul@gmail.com>
 Date: Thu, 7 Sep 2023 22:02:27 -0700
-Subject: [PATCH 2/4] Make serializer public
+Subject: [PATCH 2/5] Make serializer public
 
 ---
  include/nlohmann/detail/output/serializer.hpp | 4 +++-

upstream_utils/json_patches/0003-Make-dump_escaped-take-std-string_view.patch

@@ -1,7 +1,7 @@
 From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
 From: Tyler Veness <calcmogul@gmail.com>
 Date: Fri, 8 Sep 2023 21:42:01 -0700
-Subject: [PATCH 3/4] Make dump_escaped() take std::string_view
+Subject: [PATCH 3/5] Make dump_escaped() take std::string_view
 
 ---
  include/nlohmann/detail/output/serializer.hpp | 2 +-

upstream_utils/json_patches/0004-Add-llvm-stream-support.patch

@@ -1,7 +1,7 @@
 From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
 From: PJ Reiniger <pj.reiniger@gmail.com>
 Date: Wed, 20 Sep 2023 02:23:10 -0400
-Subject: [PATCH 4/4] Add llvm stream support
+Subject: [PATCH 4/5] Add llvm stream support
 
 ---
  .../detail/output/output_adapters.hpp         | 26 +++++++++++++++++++

upstream_utils/json_patches/0005-Fix-Doxygen-warnings.patch

@@ -0,0 +1,93 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: Gold856 <117957790+Gold856@users.noreply.github.com>
+Date: Tue, 27 May 2025 23:39:02 -0400
+Subject: [PATCH 5/5] Fix Doxygen warnings
+
+---
+ include/nlohmann/json.hpp | 31 ++++++-------------------------
+ 1 file changed, 6 insertions(+), 25 deletions(-)
+
+diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp
+index a89e2151e589663ba487a462c3d15cd247ff06cf..a5b4f8b4a118c1f5763ec6ba596a8a2d3d5791eb 100644
+--- a/include/nlohmann/json.hpp
++++ b/include/nlohmann/json.hpp
+@@ -161,7 +161,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
+     using serializer = ::nlohmann::detail::serializer<basic_json>;
+ 
+     using value_t = detail::value_t;
+-    /// JSON Pointer, see @ref nlohmann::json_pointer
++    /// JSON Pointer, see @ref json_pointer
+     using json_pointer = ::nlohmann::json_pointer<StringType>;
+     template<typename T, typename SFINAE>
+     using json_serializer = JSONSerializer<T, SFINAE>;
+@@ -173,7 +173,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
+     using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
+ 
+     using input_format_t = detail::input_format_t;
+-    /// SAX interface type, see @ref nlohmann::json_sax
++    /// SAX interface type, see nlohmann::json_sax
+     using json_sax_t = json_sax<basic_json>;
+ 
+     ////////////////
+@@ -1606,13 +1606,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
+ 
+     @throw what @ref json_serializer<ValueType> `from_json()` method throws
+ 
+-    @liveexample{The example below shows several conversions from JSON values
+-    to other types. There a few things to note: (1) Floating-point numbers can
+-    be converted to integers\, (2) A JSON array can be converted to a standard
+-    `std::vector<short>`\, (3) A JSON object can be converted to C++
+-    associative containers such as `std::unordered_map<std::string\,
+-    json>`.,get__ValueType_const}
+-
+     @since version 2.1.0
+     */
+     template < typename ValueType,
+@@ -1678,7 +1671,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
+ 
+     @return a copy of *this, converted into @a BasicJsonType
+ 
+-    @complexity Depending on the implementation of the called `from_json()`
++    Complexity: Depending on the implementation of the called `from_json()`
+                 method.
+ 
+     @since version 3.2.0
+@@ -1702,7 +1695,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
+ 
+     @return a copy of *this
+ 
+-    @complexity Constant.
++    Complexity: Constant.
+ 
+     @since version 2.1.0
+     */
+@@ -1786,12 +1779,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
+     @return pointer to the internally stored JSON value if the requested
+     pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
+ 
+-    @complexity Constant.
+-
+-    @liveexample{The example below shows how pointers to internal values of a
+-    JSON value can be requested. Note that no type conversions are made and a
+-    `nullptr` is returned if the value and the requested pointer type does not
+-    match.,get__PointerType}
++    Complexity: Constant.
+ 
+     @sa see @ref get_ptr() for explicit pointer-member access
+ 
+@@ -1883,14 +1871,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
+     to the JSON value type (e.g., the JSON value is of type boolean, but a
+     string is requested); see example below
+ 
+-    @complexity Linear in the size of the JSON value.
+-
+-    @liveexample{The example below shows several conversions from JSON values
+-    to other types. There a few things to note: (1) Floating-point numbers can
+-    be converted to integers\, (2) A JSON array can be converted to a standard
+-    `std::vector<short>`\, (3) A JSON object can be converted to C++
+-    associative containers such as `std::unordered_map<std::string\,
+-    json>`.,operator__ValueType}
++    Complexity: Linear in the size of the JSON value.
+ 
+     @since version 1.0.0
+     */

wpinet/src/main/native/include/wpinet/uv/FsEvent.h

@@ -49,7 +49,7 @@ class FsEvent final : public HandleImpl<FsEvent, uv_fs_event_t> {
    * Start watching the specified path for changes.
    *
    * @param path Path to watch for changes
-   * @param events Bitmask of event flags.  Only UV_FS_EVENT_RECURSIVE is
+   * @param flags Bitmask of event flags.  Only UV_FS_EVENT_RECURSIVE is
    *               supported (and only on OSX and Windows).
    */
   void Start(std::string_view path, unsigned int flags = 0);

wpinet/src/main/native/include/wpinet/uv/GetNameInfo.h

@@ -87,7 +87,6 @@ void GetNameInfo(Loop& loop,
  * @param callback Callback function to call when resolution completes
  * @param addr Initialized `sockaddr_in` or `sockaddr_in6` data structure.
  * @param flags Optional flags to modify the behavior of `getnameinfo`.
- * @return Connection object for the callback
  */
 inline void GetNameInfo(const std::shared_ptr<Loop>& loop,
                         std::function<void(const char*, const char*)> callback,

wpinet/src/main/native/include/wpinet/uv/Stream.h

@@ -90,7 +90,6 @@ class Stream : public Handle {
    * complete.  Errors will be reported to the stream error handler.
    *
    * @param callback Callback function to call when shutdown completes
-   * @return Connection object for the callback
    */
   void Shutdown(std::function<void()> callback = nullptr);
 

wpinet/src/main/native/include/wpinet/uv/Udp.h

@@ -146,7 +146,6 @@ class Udp final : public HandleImpl<Udp, uv_udp_t> {
    *
    * @param ip The address to which to bind.
    * @param port The port to which to bind.
-   * @param flags Optional additional flags.
    */
   void Connect6(std::string_view ip, unsigned int port);
 

wpiutil/src/main/native/thirdparty/json/include/wpi/json.h

@@ -161,7 +161,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     using serializer = ::wpi::detail::serializer<basic_json>;
 
     using value_t = detail::value_t;
-    /// JSON Pointer, see @ref wpi::json_pointer
+    /// JSON Pointer, see @ref json_pointer
     using json_pointer = ::wpi::json_pointer<StringType>;
     template<typename T, typename SFINAE>
     using json_serializer = JSONSerializer<T, SFINAE>;
@@ -173,7 +173,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
 
     using input_format_t = detail::input_format_t;
-    /// SAX interface type, see @ref wpi::json_sax
+    /// SAX interface type, see wpi::json_sax
     using json_sax_t = json_sax<basic_json>;
 
     ////////////////
@@ -1606,13 +1606,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     @throw what @ref json_serializer<ValueType> `from_json()` method throws
 
-    @liveexample{The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers\, (2) A JSON array can be converted to a standard
-    `std::vector<short>`\, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string\,
-    json>`.,get__ValueType_const}
-
     @since version 2.1.0
     */
     template < typename ValueType,
@@ -1678,7 +1671,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     @return a copy of *this, converted into @a BasicJsonType
 
-    @complexity Depending on the implementation of the called `from_json()`
+    Complexity: Depending on the implementation of the called `from_json()`
                 method.
 
     @since version 3.2.0
@@ -1702,7 +1695,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     @return a copy of *this
 
-    @complexity Constant.
+    Complexity: Constant.
 
     @since version 2.1.0
     */
@@ -1786,12 +1779,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     @return pointer to the internally stored JSON value if the requested
     pointer type @a PointerType fits to the JSON value; `nullptr` otherwise
 
-    @complexity Constant.
-
-    @liveexample{The example below shows how pointers to internal values of a
-    JSON value can be requested. Note that no type conversions are made and a
-    `nullptr` is returned if the value and the requested pointer type does not
-    match.,get__PointerType}
+    Complexity: Constant.
 
     @sa see @ref get_ptr() for explicit pointer-member access
 
@@ -1883,14 +1871,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     to the JSON value type (e.g., the JSON value is of type boolean, but a
     string is requested); see example below
 
-    @complexity Linear in the size of the JSON value.
-
-    @liveexample{The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers\, (2) A JSON array can be converted to a standard
-    `std::vector<short>`\, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string\,
-    json>`.,operator__ValueType}
+    Complexity: Linear in the size of the JSON value.
 
     @since version 1.0.0
     */