Team2890/allwpilib
4
0
Fork 0
mirror of https://github.com/wpilibsuite/allwpilib synced 2026-06-19 00:41:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

[bazel] Build wpilibc docs with doxygen (#8157)

Browse Source 
Signed-off-by: Austin Schuh <austin.linux@gmail.com>
This commit is contained in:
Austin Schuh
2025-08-04 22:49:47 -07:00
committed by GitHub
parent dffa2542c9
commit 13852760f6
17 changed files with 374 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
BUILD.bazel
View File

@@ -3,6 +3,11 @@ load("@rules_pkg//:mappings.bzl", "pkg_files")
load("@rules_python//python:pip.bzl", "compile_pip_requirements")
load("//shared/bazel/rules:publishing.bzl", "publish_all")
exports_files([
"LICENSE.md",
"ThirdPartyNotices.txt",
])
pkg_files(
name = "license_pkg_files",
srcs = [
@@ -55,59 +60,64 @@ write_source_files(
publish_all(
name = "publish",
targets = [
"//apriltag:apriltag-cpp_publish",
"//apriltag:apriltag-java_publish",
"//cameraserver:cameraserver-cpp_publish",
"//cameraserver:cameraserver-java_publish",
"//cscore:cscore-cpp_publish",
"//cscore:cscore-java_publish",
"//datalog:datalog-cpp_publish",
"//datalog:datalog-java_publish",
"//datalogtool:datalogtool_publish",
"//epilogue-processor:processor-java_publish",
"//processstarter:processstarter_publish",
"//epilogue-runtime:epilogue-java_publish",
"//fieldImages:fieldImages-cpp_publish",
"//fieldImages:fieldImages-java_publish",
"//glass:glassapp_publish",
"//glass:glass-cpp_publish",
"//glass:glassnt-cpp_publish",
"//hal:hal-java_publish",
"//hal:wpiHal-cpp_publish",
"//ntcore:ntcore-cpp_publish",
"//ntcore:ntcore-java_publish",
"//ntcoreffi:ntcoreffi-cpp_publish",
"//outlineviewer:outlineviewer_publish",
"//romiVendordep:romiVendordep-cpp_publish",
"//romiVendordep:romiVendordep-java_publish",
"//simulation/halsim_ds_socket:halsim_ds_socket-cpp_publish",
"//simulation/halsim_gui:halsim_gui-cpp_publish",
"//simulation/halsim_ws_client:halsim_ws_client-cpp_publish",
"//simulation/halsim_ws_core:halsim_ws_core-cpp_publish",
"//simulation/halsim_ws_server:halsim_ws_server-cpp_publish",
"//simulation/halsim_xrp:halsim_xrp-cpp_publish",
"//sysid:sysid_publish",
"//thirdparty/googletest:googletest-cpp_publish",
"//thirdparty/imgui_suite:imguiSuite-cpp_publish",
"//wpigui:wpigui-cpp_publish",
"//wpilibNewCommands:wpilibNewCommands-cpp_publish",
"//wpilibNewCommands:wpilibNewCommands-java_publish",
"//wpilibc:wpilibc-cpp_publish",
"//wpilibcExamples:commands_publish",
"//wpilibcExamples:examples_publish",
"//wpilibcExamples:templates_publish",
"//wpilibj:wpilibj-java_publish",
"//wpilibjExamples:commands_publish",
"//wpilibjExamples:examples_publish",
"//wpilibjExamples:templates_publish",
"//wpimath:wpimath-cpp_publish",
"//wpimath:wpimath-java_publish",
"//wpinet:wpinet-cpp_publish",
"//wpinet:wpinet-java_publish",
"//wpiunits:wpiunits-java_publish",
"//wpiutil:wpiutil-cpp_publish",
"//wpiutil:wpiutil-java_publish",
"//xrpVendordep:xrpVendordep-cpp_publish",
"//xrpVendordep:xrpVendordep-java_publish",
],
"//apriltag:apriltag-cpp_publish.publish",
"//apriltag:apriltag-java_publish.publish",
"//cameraserver:cameraserver-cpp_publish.publish",
"//cameraserver:cameraserver-java_publish.publish",
"//cscore:cscore-cpp_publish.publish",
"//cscore:cscore-java_publish.publish",
"//datalog:datalog-cpp_publish.publish",
"//datalog:datalog-java_publish.publish",
"//datalogtool:datalogtool_publish.publish",
"//epilogue-processor:processor-java_publish.publish",
"//processstarter:processstarter_publish.publish",
"//epilogue-runtime:epilogue-java_publish.publish",
"//fieldImages:fieldImages-cpp_publish.publish",
"//fieldImages:fieldImages-java_publish.publish",
"//glass:glassapp_publish.publish",
"//glass:glass-cpp_publish.publish",
"//glass:glassnt-cpp_publish.publish",
"//hal:hal-java_publish.publish",
"//hal:wpiHal-cpp_publish.publish",
"//ntcore:ntcore-cpp_publish.publish",
"//ntcore:ntcore-java_publish.publish",
"//ntcoreffi:ntcoreffi-cpp_publish.publish",
"//outlineviewer:outlineviewer_publish.publish",
"//romiVendordep:romiVendordep-cpp_publish.publish",
"//romiVendordep:romiVendordep-java_publish.publish",
"//simulation/halsim_ds_socket:halsim_ds_socket-cpp_publish.publish",
"//simulation/halsim_gui:halsim_gui-cpp_publish.publish",
"//simulation/halsim_ws_client:halsim_ws_client-cpp_publish.publish",
"//simulation/halsim_ws_core:halsim_ws_core-cpp_publish.publish",
"//simulation/halsim_ws_server:halsim_ws_server-cpp_publish.publish",
"//simulation/halsim_xrp:halsim_xrp-cpp_publish.publish",
"//sysid:sysid_publish.publish",
"//thirdparty/googletest:googletest-cpp_publish.publish",
"//thirdparty/imgui_suite:imguiSuite-cpp_publish.publish",
"//wpigui:wpigui-cpp_publish.publish",
"//wpilibNewCommands:wpilibNewCommands-cpp_publish.publish",
"//wpilibNewCommands:wpilibNewCommands-java_publish.publish",
"//wpilibc:wpilibc-cpp_publish.publish",
"//wpilibcExamples:commands_publish.publish",
"//wpilibcExamples:examples_publish.publish",
"//wpilibcExamples:templates_publish.publish",
"//wpilibj:wpilibj-java_publish.publish",
"//wpilibjExamples:commands_publish.publish",
"//wpilibjExamples:examples_publish.publish",
"//wpilibjExamples:templates_publish.publish",
"//wpimath:wpimath-cpp_publish.publish",
"//wpimath:wpimath-java_publish.publish",
"//wpinet:wpinet-cpp_publish.publish",
"//wpinet:wpinet-java_publish.publish",
"//wpiunits:wpiunits-java_publish.publish",
"//wpiutil:wpiutil-cpp_publish.publish",
"//wpiutil:wpiutil-java_publish.publish",
"//xrpVendordep:xrpVendordep-cpp_publish.publish",
"//xrpVendordep:xrpVendordep-java_publish.publish",
] + select({
"@platforms//cpu:x86_64": [
"//docs:wpilibc_publish.publish",
],
"//conditions:default": [],
}),
)

34
WORKSPACE
View File

@@ -85,6 +85,13 @@ http_archive(
],
)
http_archive(
name = "rules_doxygen",
sha256 = "5d154d3d011208510392b5aee8ea23ec61ab858cc1f3382b6eb8c729d3b4b336",
strip_prefix = "rules_doxygen-2.4.2",
url = "https://github.com/TendTo/rules_doxygen/releases/download/2.4.2/rules_doxygen-2.4.2.tar.gz",
)
load("@bazel_features//:deps.bzl", "bazel_features_deps")
bazel_features_deps()
@@ -374,3 +381,30 @@ publishing_repo(
load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
bazel_skylib_workspace()
load("@rules_doxygen//:extensions.bzl", "doxygen_repository")
# Download the os specific version 1.12.0 of doxygen supporting all the indicated platforms
doxygen_repository(
name = "doxygen",
executables = [
"",
"",
"",
],
platforms = [
"windows",
"mac",
"linux",
],
sha256s = [
"07f1c92cbbb32816689c725539c0951f92c6371d3d7f66dfa3192cbe88dd3138",
"6ace7dde967d41f4e293d034a67eb2c7edd61318491ee3131112173a77344001",
"3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647",
],
versions = [
"1.12.0",
"1.12.0",
"1.12.0",
],
)

9
apriltag/BUILD.bazel
View File

@@ -8,6 +8,15 @@ load("//shared/bazel/rules:jni_rules.bzl", "wpilib_jni_cc_library", "wpilib_jni_
load("//shared/bazel/rules:packaging.bzl", "package_minimal_jni_project")
load("//shared/bazel/rules/gen:gen-resources.bzl", "generate_resources")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/main/native/include/**/*",
"src/main/native/thirdparty/apriltag/include/**/*",
]),
visibility = ["//visibility:public"],
)
pkg_files(
name = "thirdparty-apriltag-src-pkg",
srcs = glob(["src/main/native/thirdparty/apriltag/include/**"]),

8
cameraserver/BUILD.bazel
View File

@@ -5,6 +5,14 @@ load("//shared/bazel/rules:cc_rules.bzl", "wpilib_cc_library", "wpilib_cc_shared
load("//shared/bazel/rules:java_rules.bzl", "wpilib_java_library")
load("//shared/bazel/rules:packaging.bzl", "package_minimal_cc_project")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/main/native/include/**/*",
]),
visibility = ["//visibility:public"],
)
wpilib_cc_library(
name = "cameraserver",
srcs = glob(["src/main/native/cpp/**"]),

8
cscore/BUILD.bazel
View File

@@ -7,6 +7,14 @@ load("//shared/bazel/rules:jni_rules.bzl", "wpilib_jni_cc_library", "wpilib_jni_
load("//shared/bazel/rules:objectivec_rules.bzl", "wpilib_objc_library")
load("//shared/bazel/rules:packaging.bzl", "package_minimal_jni_project")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/main/native/include/**/*",
]),
visibility = ["//visibility:public"],
)
WIN_SRCS = glob([
"src/main/native/windows/**/*.cpp",
"src/main/native/windows/**/*.h",

102
docs/BUILD.bazel Normal file
View File

@@ -0,0 +1,102 @@
load("@aspect_bazel_lib//lib:copy_file.bzl", "copy_file")
load("@doxygen//:doxygen.bzl", "doxygen")
load("@rules_jvm_external//:defs.bzl", "maven_export")
load("@rules_pkg//:pkg.bzl", "pkg_zip")
paths = [
"apriltag/src/main/native/include",
"cameraserver/src/generated/main/native/include",
"cameraserver/src/main/native/include",
"cscore/src/main/native/include",
"hal/src/main/native/include",
"ntcore/src/main/native/include",
"romiVendordep/src/generated/main/native/include",
"romiVendordep/src/main/native/include",
"wpilibNewCommands/src/generated/main/native/include",
"wpilibNewCommands/src/main/native/include",
"wpilibc/src/generated/main/native/include",
"wpilibc/src/main/native/include",
"wpimath/src/main/native/include",
"wpinet/src/main/native/include",
"wpiutil/src/main/native/include",
"wpiutil/src/main/native/thirdparty/argparse/include",
"wpiutil/src/main/native/thirdparty/debugging/include",
"wpiutil/src/main/native/thirdparty/expected/include",
"wpiutil/src/main/native/thirdparty/fmtlib/include",
"wpiutil/src/main/native/thirdparty/json/include",
"wpiutil/src/main/native/thirdparty/llvm/include",
"wpiutil/src/main/native/thirdparty/mpack/include",
"wpiutil/src/main/native/thirdparty/nanopb/include",
"wpiutil/src/main/native/thirdparty/protobuf/include",
"wpiutil/src/main/native/thirdparty/sigslot/include",
"xrpVendordep/src/generated/main/native/include",
"xrpVendordep/src/main/native/include",
]
# Doxygen library includes '.' if we include these from their original path.
# That pulls in external/* and all sorts of other mess.
# Instead, copy them here so we instead include 'docs'
copy_file(
name = "license",
src = "//:LICENSE.md",
out = "LICENSE.md",
allow_symlink = False,
is_executable = False,
)
copy_file(
name = "third_party_notices",
src = "//:ThirdPartyNotices.txt",
out = "ThirdPartyNotices.txt",
allow_symlink = False,
is_executable = False,
)
doxygen(
name = "doxygen",
srcs = [
":license",
":theme.css",
":third_party_notices",
"//apriltag:doxygen-files",
"//cameraserver:doxygen-files",
"//cscore:doxygen-files",
"//hal:doxygen-files",
"//ntcore:doxygen-files",
"//romiVendordep:doxygen-files",
"//wpilibNewCommands:doxygen-files",
"//wpilibc:doxygen-files",
"//wpimath:doxygen-files",
"//wpinet:doxygen-files",
"//wpiutil:doxygen-files",
"//wpiutil:src/main/native/resources/wpilib-128.png",
"//xrpVendordep:doxygen-files",
],
outs = ["html"],
doxyfile_template = "Doxyfile",
exclude = "wpiutil/src/main/native/resources/wpilib-128.png docs/theme.css",
html_extra_stylesheet = "docs/theme.css",
project_logo = "wpiutil/src/main/native/resources/wpilib-128.png",
project_name = "WPILibC++",
project_number = "$(WPILIB_VERSION)",
strip_from_inc_path = paths,
strip_from_path = paths,
target_compatible_with = select({
"@platforms//cpu:x86_64": [],
"//conditions:default": ["@platforms//:incompatible"],
}),
warnings = "NO",
)
pkg_zip(
name = "doxygen-zip",
srcs = [":doxygen"],
strip_prefix = "html",
)
maven_export(
name = "wpilibc_publish",
maven_coordinates = "edu.wpi.first.wpilibc:documentation:$(WPILIB_VERSION)",
target = ":doxygen-zip",
visibility = ["//visibility:public"],
)

6
docs/Doxyfile
View File

@@ -972,6 +972,7 @@ WARN_LOGFILE =
# Note: If this tag is empty the current directory is searched.
INPUT =
# {{INPUT}}
# This tag can be used to specify the character encoding of the source files
# that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2783,6 +2784,7 @@ INTERACTIVE_SVG = NO
# This tag requires that the tag HAVE_DOT is set to YES.
DOT_PATH =
# {{DOT_PATH}}
# The DOTFILE_DIRS tag can be used to specify one or more directories that
# contain dot files that are included in the documentation (see the \dotfile
@@ -2889,3 +2891,7 @@ MSCGEN_TOOL =
# command).
MSCFILE_DIRS =
# {{ADDITIONAL PARAMETERS}}
# {{OUTPUT DIRECTORY}}

9
hal/BUILD.bazel
View File

@@ -9,6 +9,15 @@ load("//shared/bazel/rules:java_rules.bzl", "wpilib_java_junit5_test")
load("//shared/bazel/rules:jni_rules.bzl", "wpilib_jni_cc_library", "wpilib_jni_java_library")
load("//shared/bazel/rules:packaging.bzl", "package_minimal_jni_project")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/main/native/include/**/*.h",
"src/mrc/include/**/*.h",
]),
visibility = ["//visibility:public"],
)
filegroup(
name = "proto_files",
srcs = glob(["src/mrc/proto/**/*.proto"]),

9
ntcore/BUILD.bazel
View File

@@ -9,6 +9,15 @@ load("//shared/bazel/rules:java_rules.bzl", "wpilib_java_junit5_test")
load("//shared/bazel/rules:jni_rules.bzl", "wpilib_jni_cc_library", "wpilib_jni_java_library")
load("//shared/bazel/rules:packaging.bzl", "package_default_jni_project")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/generated/main/native/include/**/*",
"src/main/native/include/**/*",
]),
visibility = ["//visibility:public"],
)
generate_ntcore(
name = "generate_ntcore",
)

8
romiVendordep/BUILD.bazel
View File

@@ -4,6 +4,14 @@ load("//shared/bazel/rules:cc_rules.bzl", "wpilib_cc_library", "wpilib_cc_shared
load("//shared/bazel/rules:java_rules.bzl", "wpilib_java_library")
load("//shared/bazel/rules:packaging.bzl", "package_minimal_cc_project")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/main/native/include/**/*",
]),
visibility = ["//visibility:public"],
)
wpilib_cc_library(
name = "romiVendordep",
srcs = glob([

74
shared/bazel/rules/publishing.bzl
View File

@@ -1,11 +1,9 @@
"""Bazel rules for publishing maven artifacts."""
load("@bazel_skylib//rules:write_file.bzl", "write_file")
load("@com_wpilib_allwpilib_publishing_config//:publishing_config.bzl", "CLASSIFIER_FILTER")
load("@platforms//host:constraints.bzl", _host_constraints = "HOST_CONSTRAINTS")
load("@rules_jvm_external//:defs.bzl", "maven_export")
load("@rules_pkg//pkg:zip.bzl", "pkg_zip")
load("@rules_shell//shell:sh_binary.bzl", "sh_binary")
load("//shared/bazel/rules:transitions.bzl", "platform_transition_filegroup")
def _get_host_os():
@@ -19,31 +17,59 @@ def _get_host_os():
HOST_OS = _get_host_os()
def publish_all(name, targets):
"""Macro to publish multiple maven artifacts with 1 call."""
publish_name = name + "_publish_all"
write_file(
name = publish_name,
out = publish_name + ".sh",
content = [
"#!/bin/bash",
"set -e",
"",
'for arg in "$@";',
"do",
' "$arg"',
"done",
],
tags = ["manual"],
def _publish_all_impl(ctx):
# This is a rule, not a macro, to allow the `targets` attribute to be
# configurable with `select()`. Macros are expanded during the loading phase,
# before `select()` is resolved, which makes this impossible with a macro.
#
# This rule works by generating a shell script that executes all of the publisher
# scripts from the `targets` attribute. This runs at execution time (`bazel run`)
# rather than build time.
script = ctx.actions.declare_file(ctx.label.name + "_runner.sh")
executables = [target.files_to_run.executable for target in ctx.attr.targets]
script_content = """#!/bin/bash
set -e
for arg in {publish_scripts}; do
"$arg" "$@"
done
""".format(
publish_scripts = " ".join(["'" + e.short_path + "'" for e in executables]),
)
sh_binary(
name = name,
srcs = [publish_name + ".sh"],
args = ["$(location " + x + ".publish)" for x in targets],
data = [x + ".publish" for x in targets],
tags = ["manual"],
ctx.actions.write(
output = script,
content = script_content,
is_executable = True,
)
# The publisher scripts have their own dependencies (runfiles), which must be
# collected and merged so they are available when our runner script executes.
all_runfiles = [ctx.runfiles(files = executables)]
for target in ctx.attr.targets:
all_runfiles.append(target[DefaultInfo].default_runfiles)
return [
DefaultInfo(
runfiles = ctx.runfiles().merge_all(all_runfiles),
executable = script,
),
]
publish_all = rule(
doc = "Rule to publish multiple maven artifacts with a single `bazel run` command.",
implementation = _publish_all_impl,
attrs = {
"targets": attr.label_list(
doc = "A list of targets to publish. These are typically the `.publish` targets from `maven_export`.",
providers = [DefaultInfo],
),
},
executable = True,
)
host_architectures = {
"@rules_bzlmodrio_toolchains//platforms/linux_x86_64": "linux-x86-64",
"@rules_bzlmodrio_toolchains//platforms/osx": "osxuniversal",

9
wpilibNewCommands/BUILD.bazel
View File

@@ -8,6 +8,15 @@ load("//shared/bazel/rules:java_rules.bzl", "wpilib_java_junit5_test", "wpilib_j
load("//shared/bazel/rules:packaging.bzl", "package_minimal_cc_project")
load("//wpilibNewCommands:generate.bzl", "generate_wpilib_new_commands")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/generated/main/native/include/**/*",
"src/main/native/include/**/*",
]),
visibility = ["//visibility:public"],
)
py_binary(
name = "generate_hids",
srcs = ["generate_hids.py"],

9
wpilibc/BUILD.bazel
View File

@@ -8,6 +8,15 @@ load("//shared/bazel/rules:packaging.bzl", "package_minimal_cc_project")
load("//shared/bazel/rules/gen:gen-version-file.bzl", "generate_version_file")
load("//wpilibc:generate.bzl", "generate_wpilibc")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/generated/main/native/include/**/*",
"src/main/native/include/**/*",
]),
visibility = ["//visibility:public"],
)
py_binary(
name = "generate_hids",
srcs = ["generate_hids.py"],

11
wpimath/BUILD.bazel
View File

@@ -10,6 +10,17 @@ load("//shared/bazel/rules:jni_rules.bzl", "wpilib_jni_cc_library", "wpilib_jni_
load("//shared/bazel/rules:packaging.bzl", "package_default_jni_project")
load("//wpimath:generate.bzl", "generate_wpimath")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/generated/main/native/cpp/wpimath/protobuf/*.h",
"src/main/native/include/**/*",
"src/main/native/thirdparty/gcem/include/**/*",
"src/main/native/thirdparty/sleipnir/include/**/*",
]),
visibility = ["//visibility:public"],
)
filegroup(
name = "templates",
srcs = glob(["src/generate/main/java/*.jinja"]),

10
wpinet/BUILD.bazel
View File

@@ -7,6 +7,16 @@ load("//shared/bazel/rules:jni_rules.bzl", "wpilib_jni_cc_library", "wpilib_jni_
load("//shared/bazel/rules:packaging.bzl", "package_minimal_jni_project")
load("//shared/bazel/rules/gen:gen-resources.bzl", "generate_resources")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/main/native/include/**/*",
"src/main/native/thirdparty/libuv/include/**/*",
"src/main/native/thirdparty/tcpsockets/include/**/*",
]),
visibility = ["//visibility:public"],
)
WIN_UV_SRCS = glob([
"src/main/native/thirdparty/libuv/src/win/*.cpp",
"src/main/native/thirdparty/libuv/src/win/*.h",

19
wpiutil/BUILD.bazel
View File

@@ -10,6 +10,25 @@ load("//shared/bazel/rules:packaging.bzl", "package_default_jni_project")
load("//shared/bazel/rules/gen:gen-resources.bzl", "generate_resources")
load("//wpiutil:generate.bzl", "generate_wpiutil")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/main/native/include/**/*",
"src/main/native/thirdparty/argparse/include/**/*",
"src/main/native/thirdparty/debugging/include/**/*",
"src/main/native/thirdparty/expected/include/**/*",
"src/main/native/thirdparty/fmtlib/include/**/*",
"src/main/native/thirdparty/json/include/**/*",
"src/main/native/thirdparty/llvm/include/**/*",
"src/main/native/thirdparty/mpack/include/**/*",
"src/main/native/thirdparty/nanopb/include/**/*",
"src/main/native/thirdparty/sigslot/include/**/*",
]),
visibility = ["//visibility:public"],
)
exports_files(["src/main/native/resources/wpilib-128.png"])
py_binary(
name = "nanopb_generator",
srcs = glob(["src/main/native/thirdparty/nanopb/generator/**/*.py"]),

8
xrpVendordep/BUILD.bazel
View File

@@ -4,6 +4,14 @@ load("//shared/bazel/rules:cc_rules.bzl", "wpilib_cc_library", "wpilib_cc_shared
load("//shared/bazel/rules:java_rules.bzl", "wpilib_java_library")
load("//shared/bazel/rules:packaging.bzl", "package_minimal_cc_project")
filegroup(
name = "doxygen-files",
srcs = glob([
"src/main/native/include/**/*",
]),
visibility = ["//visibility:public"],
)
wpilib_cc_library(
name = "xrpVendordep",
srcs = glob([