Skip to content

Commit 1c220eb

Browse files
Gold856Gold856
authored
[build] CMake: add Doxygen doc generation (#7286)
1 parent 1cfed73 commit 1c220eb

File tree

2 files changed

+158
-0
lines changed

2 files changed

+158
-0
lines changed

‎CMakeLists.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,14 @@ set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
6666
option(BUILD_SHARED_LIBS "Build with shared libs (needed for JNI)" ON)
6767
option(WITH_JAVA "Include Java and JNI in the build" OFF)
6868
option(WITH_JAVA_SOURCE "Build Java source jars" ${WITH_JAVA})
69+
option(WITH_DOCS "Build Doxygen docs (needs Git for versioning)" OFF)
70+
cmake_dependent_option(
71+
DOCS_WARNINGS_AS_ERRORS
72+
"Make docs warnings into errors"
73+
OFF
74+
WITH_DOCS
75+
OFF
76+
)
6977
option(WITH_CSCORE "Build cscore (needs OpenCV)" ON)
7078
option(WITH_NTCORE "Build ntcore" ON)
7179
option(WITH_WPIMATH "Build wpimath" ON)
@@ -129,6 +137,12 @@ else()
129137
find_package(Java REQUIRED COMPONENTS Runtime)
130138
endif()
131139

140+
if(WITH_DOCS)
141+
find_package(Doxygen REQUIRED)
142+
find_package(Git REQUIRED)
143+
include(AddDoxygenDocs)
144+
add_doxygen_docs()
145+
endif()
132146
find_package(LIBSSH CONFIG 0.7.1)
133147

134148
set(CMAKE_FIND_PACKAGE_PREFER_CONFIG ON)

‎cmake/modules/AddDoxygenDocs.cmake‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
macro(add_doxygen_docs)
2+
set(dirs
3+
apriltag
4+
cameraserver
5+
cscore
6+
fieldImages
7+
hal
8+
ntcore
9+
romiVendordep
10+
wpilibc
11+
wpilibNewCommands
12+
wpimath
13+
wpinet
14+
wpiutil
15+
xrpVendordep
16+
)
17+
foreach(dir ${dirs})
18+
list(APPEND docs_dirs ${dir}/src/main/native/include)
19+
file(GLOB dirs ${dir}/src/main/native/thirdparty/*/include)
20+
list(FILTER dirs EXCLUDE REGEX eigen|protobuf)
21+
set(DOXYGEN_EXCLUDE_PATTERNS "*.pb.h" "**/.clang-tidy" "**/.clang-format")
22+
23+
if(DOCS_WARNINGS_AS_ERRORS)
24+
set(DOXYGEN_WARN_AS_ERROR "FAIL_ON_WARNINGS_PRINT")
25+
list(FILTER dirs EXCLUDE REGEX fmt|memory|units)
26+
list(
27+
APPEND
28+
DOXYGEN_EXCLUDE_PATTERNS
29+
# apriltag
30+
"apriltag_pose.h"
31+
# llvm
32+
"wpi/AlignOf.h"
33+
"wpi/Casting.h"
34+
"wpi/Chrono.h"
35+
"wpi/Compiler.h"
36+
"wpi/ConvertUTF.h"
37+
"wpi/DenseMap.h"
38+
"wpi/DenseMapInfo.h"
39+
"wpi/Endian.h"
40+
"wpi/EpochTracker.h"
41+
"wpi/Errc.h"
42+
"wpi/Errno.h"
43+
"wpi/ErrorHandling.h"
44+
"wpi/bit.h"
45+
"wpi/fs.h"
46+
"wpi/FunctionExtras.h"
47+
"wpi/function_ref.h"
48+
"wpi/Hashing.h"
49+
"wpi/iterator.h"
50+
"wpi/iterator_range.h"
51+
"wpi/ManagedStatic.h"
52+
"wpi/MapVector.h"
53+
"wpi/MathExtras.h"
54+
"wpi/MemAlloc.h"
55+
"wpi/PointerIntPair.h"
56+
"wpi/PointerLikeTypeTraits.h"
57+
"wpi/PointerUnion.h"
58+
"wpi/raw_os_ostream.h"
59+
"wpi/raw_ostream.h"
60+
"wpi/SmallPtrSet.h"
61+
"wpi/SmallSet.h"
62+
"wpi/SmallString.h"
63+
"wpi/SmallVector.h"
64+
"wpi/StringExtras.h"
65+
"wpi/StringMap.h"
66+
"wpi/SwapByteOrder.h"
67+
"wpi/type_traits.h"
68+
"wpi/VersionTuple.h"
69+
"wpi/WindowsError.h"
70+
# libuv
71+
"uv.h"
72+
"uv/**"
73+
# json
74+
"wpi/adl_serializer.h"
75+
"wpi/byte_container_with_subtype.h"
76+
"wpi/json.h"
77+
"wpi/json_fwd.h"
78+
"wpi/ordered_map.h"
79+
# mpack
80+
"wpi/mpack.h"
81+
)
82+
endif()
83+
list(APPEND docs_dirs ${dirs})
84+
list(APPEND docs_dirs ${dir}/src/generated/main/native/include)
85+
endforeach()
86+
87+
set(DOXYGEN_CASE_SENSE_NAMES false)
88+
set(DOXYGEN_EXTENSION_MAPPING inc=C++ no_extension=C++)
89+
set(DOXYGEN_EXTRACT_ALL true)
90+
set(DOXYGEN_EXTRACT_STATIC true)
91+
set(DOXYGEN_FILE_PATTERNS "*")
92+
set(DOXYGEN_FULL_PATH_NAMES true)
93+
set(DOXYGEN_FULL_SIDEBAR false)
94+
set(DOXYGEN_GENERATE_HTML true)
95+
set(DOXYGEN_GENERATE_LATEX false)
96+
set(DOXYGEN_GENERATE_TREEVIEW true)
97+
set(DOXYGEN_HTML_COLORSTYLE "LIGHT")
98+
set(DOXYGEN_HTML_EXTRA_STYLESHEET docs/theme.css)
99+
set(DOXYGEN_JAVADOC_AUTOBRIEF true)
100+
set(DOXYGEN_ALIASES
101+
"effects=\\par <i>Effects:</i>^^"
102+
"notes=\\par <i>Notes:</i>^^"
103+
"requires=\\par <i>Requires:</i>^^"
104+
"requiredbe=\\par <i>Required Behavior:</i>^^"
105+
"concept{2}=<a href=\"md_doc_concepts.html#1\">2</a>"
106+
"defaultbe=\\par <i>Default Behavior:</i>^^"
107+
)
108+
set(DOXYGEN_PROJECT_NAME WPILibC++)
109+
set(DOXYGEN_PROJECT_NUMBER version)
110+
set(DOXYGEN_PROJECT_LOGO wpiutil/src/main/native/resources/wpilib-128.png)
111+
set(DOXYGEN_QUIET true)
112+
set(DOXYGEN_RECURSIVE true)
113+
set(DOXYGEN_STRIP_CODE_COMMENTS false)
114+
set(DOXYGEN_STRIP_FROM_PATH ${docs_dirs})
115+
set(DOXYGEN_STRIP_FROM_INC_PATH ${docs_dirs})
116+
set(DOXYGEN_TIMESTAMP "DATETIME")
117+
set(DOXYGEN_USE_MATHJAX true)
118+
set(DOXYGEN_WARNINGS false)
119+
set(DOXYGEN_WARN_IF_INCOMPLETE_DOC true)
120+
set(DOXYGEN_WARN_IF_UNDOCUMENTED false)
121+
set(DOXYGEN_WARN_NO_PARAMDOC true)
122+
123+
set(DOXYGEN_ENABLE_PREPROCESSING true)
124+
set(DOXYGEN_MACRO_EXPANSION true)
125+
set(DOXYGEN_EXPAND_ONLY_PREDEF true)
126+
set(DOXYGEN_PREDEFINED
127+
"__cplusplus"
128+
"HAL_ENUM(name)=enum name : int32_t"
129+
"DOXYGEN"
130+
"WPI_NOEXCEPT:=noexcept"
131+
"WPI_SFINAE(x):="
132+
"WPI_REQUIRES(x):="
133+
"WPI_REQUIRES_RET(...):="
134+
"WPI_ENABLE_IF(...):="
135+
"WPI_CONSTEXPR:=constexpr"
136+
"WPI_CONSTEXPR_FNC:=constexpr"
137+
"WPI_IMPL_DEFINED(...):=implementation_defined"
138+
"WPI_EBO(...):="
139+
)
140+
execute_process(COMMAND git describe OUTPUT_VARIABLE version)
141+
string(SUBSTRING ${version} 1 -1 version)
142+
set(DOXYGEN_PROJECT_NUMBER ${version})
143+
doxygen_add_docs(docs ${docs_dirs})
144+
endmacro()

0 commit comments

Comments
 (0)