mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Scot Breitenfeld
a46a399230
Addresses the "multiple @ param documentation sections" warnings are caused by the interaction of three things:
1. MACRO_EXPANSION = YES with EXPAND_ONLY_PREDEF = NO in Doxyfile.in
2. Versioned API macros in H5version.h like:
\def documentation in APIVersions.dox like:
3. \def H5Tarray_create \api_vers_2{H5Tarray_create,H5Tarray_create1,H5Tarray_create2}
Because Doxygen expands all macros, it sees H5Tarray_create as an alias for H5Tarray_create1. It then associates documentation from both the \def block (for the macro) and the function's own doc block (with \param entries) with the same function — resulting in "multiple @ param documentation sections."
* Update Doxygen version from 1.16.0 to 1.16.1
Use Doxygen 1.16.1 for all platforms. This version includes the latest
bug fixes and improvements while maintaining compatibility with our
documentation format.
* Fix Windows Doxygen installation for version 1.16.1
Handle different Windows binary naming conventions across Doxygen versions:
- 1.16.1 uses: doxygen-VERSION.windows.x64.bin.zip
- 1.16.0 uses: doxygen-VERSION.x64.bin.zip
Try the newer naming convention first, then fall back to the older one
if the download fails. This ensures compatibility across versions.
* Use ssciwr/doxygen-install in setup-doxygen action
Replace direct installation of official Doxygen binaries with
ssciwr/doxygen-install action. This avoids Java documentation parsing
errors that occur with official binaries but not with distribution
builds.
The setup-doxygen action now serves as a thin wrapper around
ssciwr/doxygen-install@f13be16c83 (v1),
using commit hash for security and reproducibility.
* Remove redundant version specification from workflows
The setup-doxygen action already has a default version (1.16.1),
so explicit version specification in workflows is unnecessary.
This follows DRY principles and makes version updates simpler.
83 lines
3.6 KiB
CMake
83 lines
3.6 KiB
CMake
cmake_minimum_required (VERSION 3.26)
|
|
project (HDF5_DOXYGEN C)
|
|
|
|
#-----------------------------------------------------------------------------
|
|
# Option to build documentation
|
|
#-----------------------------------------------------------------------------
|
|
string (TIMESTAMP HDF5_PACKAGE_DATE_STRING "%Y-%m-%d")
|
|
if (DOXYGEN_FOUND)
|
|
set (DOXYGEN_PACKAGE ${HDF5_PACKAGE_NAME})
|
|
# For release builds use the version from the package
|
|
# set (DOXYGEN_VERSION_STRING ${HDF5_PACKAGE_VERSION_STRING})
|
|
set (DOXYGEN_VERSION_STRING "Last Updated on ${HDF5_PACKAGE_DATE_STRING}")
|
|
set (DOXYGEN_DIR ${HDF5_DOXYGEN_DIR})
|
|
set (DOXYGEN_INCLUDE_ALIASES_PATH ${HDF5_DOXYGEN_DIR})
|
|
set (DOXYGEN_INCLUDE_ALIASES aliases)
|
|
set (DOXYGEN_VERBATIM_VARS DOXYGEN_INCLUDE_ALIASES)
|
|
set (DOXYGEN_PROJECT_LOGO ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png)
|
|
set (DOXYGEN_PROJECT_BRIEF "The HDF5 Field Guide")
|
|
set (DOXYGEN_INPUT_DIRECTORY "${HDF5_SOURCE_DIR} ${HDF5_DOXYGEN_DIR}/dox ${HDF5_GENERATED_SOURCE_DIR}")
|
|
set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
|
|
set (DOXYGEN_MACRO_EXPANSION YES)
|
|
set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs)
|
|
set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/dox/cookbook ${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/release_docs ${HDF5_TEST_SRC_DIR}")
|
|
set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml)
|
|
set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html)
|
|
set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html)
|
|
set (DOXYGEN_HTML_EXTRA_STYLESHEET "${HDF5_DOXYGEN_DIR}/hdf5doxy.css ${HDF5_DOXYGEN_DIR}/doxygen-awesome.css")
|
|
set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/doxygen-awesome-tabs.js")
|
|
set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag)
|
|
set (DOXYGEN_SERVER_BASED_SEARCH NO)
|
|
set (DOXYGEN_EXTERNAL_SEARCH NO)
|
|
set (DOXYGEN_SEARCHENGINE_URL)
|
|
set (DOXYGEN_STRIP_FROM_PATH ${HDF5_SOURCE_DIR})
|
|
set (DOXYGEN_STRIP_FROM_INC_PATH ${HDF5_SOURCE_DIR})
|
|
# Versioned API macros are added to PREDEFINED to give Doxygen a fixed
|
|
# expansion and prevent it from discovering the #defines in H5version.h,
|
|
# which otherwise causes "multiple @param documentation sections" warnings
|
|
# when the macro documentation (\def) and the function documentation both
|
|
# get associated with the same underlying function.
|
|
#
|
|
# The versioned API macros are auto-generated from src/H5vers.txt by the
|
|
# bin/make_vers script, which creates doxygen/H5version_doxygen.cmake.
|
|
# This ensures the Doxygen configuration stays synchronized with the
|
|
# actual default versions defined in src/H5version.h.
|
|
set (_doxygen_predefined_entries
|
|
H5_HAVE_DIRECT
|
|
H5_HAVE_LIBHDFS
|
|
H5_HAVE_MAP_API
|
|
H5_HAVE_PARALLEL
|
|
H5_HAVE_ROS3_VFD
|
|
H5_DOXYGEN
|
|
H5_HAVE_SUBFILING_VFD
|
|
H5_HAVE_IOC_VFD
|
|
H5_HAVE_MIRROR_VFD
|
|
"H5std_string=std::string"
|
|
"H5G_link_t=H5L_type_t"
|
|
)
|
|
# Load auto-generated versioned API macros from doxygen/H5version_doxygen.cmake
|
|
include(${HDF5_DOXYGEN_DIR}/H5version_doxygen.cmake)
|
|
list (JOIN _doxygen_predefined_entries " " DOXYGEN_PREDEFINED)
|
|
set (DOXYGEN_WARN_AS_ERROR ${HDF5_DOXY_WARNINGS})
|
|
|
|
# This configure and individual custom targets work together
|
|
# Replace variables inside @@ with the current values
|
|
configure_file (${HDF5_DOXYGEN_DIR}/Doxyfile.in ${HDF5_BINARY_DIR}/Doxyfile @ONLY)
|
|
|
|
install (
|
|
DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs/html
|
|
DESTINATION ${HDF5_INSTALL_DOC_DIR}
|
|
COMPONENT hdfdocuments
|
|
)
|
|
install (
|
|
FILES ${HDF5_BINARY_DIR}/hdf5.tag
|
|
DESTINATION ${HDF5_INSTALL_DOC_DIR}
|
|
COMPONENT hdfdocuments
|
|
)
|
|
|
|
if (NOT TARGET doxygen)
|
|
add_custom_target (doxygen)
|
|
endif ()
|
|
|
|
endif ()
|