diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml deleted file mode 100644 index e9202045d1..0000000000 --- a/.github/workflows/documentation.yml +++ /dev/null @@ -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', - }) diff --git a/.github/workflows/gradle.yml b/.github/workflows/gradle.yml index 5e8b49b54d..145949908a 100644 --- a/.github/workflows/gradle.yml +++ b/.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] diff --git a/.github/workflows/lint-format.yml b/.github/workflows/lint-format.yml index 938405e552..7075ac11cb 100644 --- a/.github/workflows/lint-format.yml +++ b/.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 }} diff --git a/docs/build.gradle b/docs/build.gradle index 93a41ef77f..a500a38961 100644 --- a/docs/build.gradle +++ b/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' diff --git a/upstream_utils/json_patches/0001-Remove-version-from-namespace.patch b/upstream_utils/json_patches/0001-Remove-version-from-namespace.patch index 945e6ea489..9a75050313 100644 --- a/upstream_utils/json_patches/0001-Remove-version-from-namespace.patch +++ b/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 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 ++------------------------ diff --git a/upstream_utils/json_patches/0002-Make-serializer-public.patch b/upstream_utils/json_patches/0002-Make-serializer-public.patch index f4d28e0530..f0d49188e3 100644 --- a/upstream_utils/json_patches/0002-Make-serializer-public.patch +++ b/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 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 +++- diff --git a/upstream_utils/json_patches/0003-Make-dump_escaped-take-std-string_view.patch b/upstream_utils/json_patches/0003-Make-dump_escaped-take-std-string_view.patch index 20a87fd047..6900627940 100644 --- a/upstream_utils/json_patches/0003-Make-dump_escaped-take-std-string_view.patch +++ b/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 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 +- diff --git a/upstream_utils/json_patches/0004-Add-llvm-stream-support.patch b/upstream_utils/json_patches/0004-Add-llvm-stream-support.patch index 3548041318..a336e8de4d 100644 --- a/upstream_utils/json_patches/0004-Add-llvm-stream-support.patch +++ b/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 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 +++++++++++++++++++ diff --git a/upstream_utils/json_patches/0005-Fix-Doxygen-warnings.patch b/upstream_utils/json_patches/0005-Fix-Doxygen-warnings.patch new file mode 100644 index 0000000000..f1909b2417 --- /dev/null +++ b/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; + + 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; + template + using json_serializer = JSONSerializer; +@@ -173,7 +173,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec + using initializer_list_t = std::initializer_list>; + + 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; + + //////////////// +@@ -1606,13 +1606,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec + + @throw what @ref json_serializer `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`\, (3) A JSON object can be converted to C++ +- associative containers such as `std::unordered_map`.,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`\, (3) A JSON object can be converted to C++ +- associative containers such as `std::unordered_map`.,operator__ValueType} ++ Complexity: Linear in the size of the JSON value. + + @since version 1.0.0 + */ diff --git a/wpinet/src/main/native/include/wpinet/uv/FsEvent.h b/wpinet/src/main/native/include/wpinet/uv/FsEvent.h index ba8a649595..1eb604da91 100644 --- a/wpinet/src/main/native/include/wpinet/uv/FsEvent.h +++ b/wpinet/src/main/native/include/wpinet/uv/FsEvent.h @@ -49,7 +49,7 @@ class FsEvent final : public HandleImpl { * 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); diff --git a/wpinet/src/main/native/include/wpinet/uv/GetNameInfo.h b/wpinet/src/main/native/include/wpinet/uv/GetNameInfo.h index 1bd0f4a594..794c8d7bf2 100644 --- a/wpinet/src/main/native/include/wpinet/uv/GetNameInfo.h +++ b/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, std::function callback, diff --git a/wpinet/src/main/native/include/wpinet/uv/Stream.h b/wpinet/src/main/native/include/wpinet/uv/Stream.h index 29e58118a6..3455d7a216 100644 --- a/wpinet/src/main/native/include/wpinet/uv/Stream.h +++ b/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 callback = nullptr); diff --git a/wpinet/src/main/native/include/wpinet/uv/Udp.h b/wpinet/src/main/native/include/wpinet/uv/Udp.h index cfa245f672..f696b06286 100644 --- a/wpinet/src/main/native/include/wpinet/uv/Udp.h +++ b/wpinet/src/main/native/include/wpinet/uv/Udp.h @@ -146,7 +146,6 @@ class Udp final : public HandleImpl { * * @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); diff --git a/wpiutil/src/main/native/thirdparty/json/include/wpi/json.h b/wpiutil/src/main/native/thirdparty/json/include/wpi/json.h index afeac0ea7e..3f854e6add 100644 --- a/wpiutil/src/main/native/thirdparty/json/include/wpi/json.h +++ b/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; 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; template using json_serializer = JSONSerializer; @@ -173,7 +173,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec using initializer_list_t = std::initializer_list>; 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; //////////////// @@ -1606,13 +1606,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @throw what @ref json_serializer `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`\, (3) A JSON object can be converted to C++ - associative containers such as `std::unordered_map`.,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`\, (3) A JSON object can be converted to C++ - associative containers such as `std::unordered_map`.,operator__ValueType} + Complexity: Linear in the size of the JSON value. @since version 1.0.0 */