Open
Description
Explain what you would like to see improved
Related to this comment #8742 (comment)
There is a way to document CMake flags so that they appear neatly within the Doxygen reference guide of ROOT.
Optional: share how it could be improved
https://github.com/ferdymercury/cmake-modules/blob/master/make_documentation.cmake
http://jesnault.fr/website/document-your-cmake-code-within-doxygen/
In the main, I use add_subdirectory(doc), and then I create a "doc" folder with a .gitignore containing cmake.dox, and then a CMakeLists.txt with more or less this structure:
## CMAKE_DOCUMENTATION_START CMakeLists.txt
##
## Main CMakeFile for compiling zdt-daq.
## Following variables can be configured when running ccmake:
## <table>
## <caption id="config-cmake">Table of configurable CMake parameters</caption>
## <tr><th>Variable <th>Values <th>Description
## <tr><td>BUILD_DOCUMENTATION <td>ON (OFF) <td>Build Doxygen HTML documentation
## <tr><td>CLI11_DIR <td>/opt/CLI11 <td>CLI11 git repository
## <tr><td>CMAKE_BUILD_TYPE <td>Release (Debug) <td>Choose the type of build
## <tr><td>ENABLE_TESTS <td>ON (OFF) <td>Build CTests
#~ ## <tr><td>FunctionalPlus_DIR <td>/opt/FunctionalPlus/install/lib/cmake/FunctionalPlus <td>FPlus install folder containing FindFunctionalPlus
## <tr><td>CMAKEMODULES_DIR <td>/opt/cmake-modules <td>rpavlik git source dir, use https://github.com/ferdymercury/cmake-modules and git checkout master
## <tr><td>ROOT_DIR <td>$ROOTSYS (/opt/root) <td>ROOT build directory
## <tr><td>ZSTR_DIR <td>/opt/zstr <td>ZSTR git repository
## </table>
##
## CMAKE_DOCUMENTATION_END
## See https://www.stack.nl/~dimitri/doxygen/manual/tables.html
# Add Doxygen documentation https://stackoverflow.com/questions/34878276/build-doxygen-from-cmake-script
### cmake-modules
if(NOT DEFINED CMAKEMODULES_DIR)
set (CMAKEMODULES_DIR "/opt/cmake-modules" CACHE STRING "cmake-modules git repository")
endif()
list(APPEND CMAKE_MODULE_PATH "${CMAKEMODULES_DIR}")
option(BUILD_DOCUMENTATION "Create and install the HTML based API documentation (requires Doxygen)" ON)
if(BUILD_DOCUMENTATION)
find_package(Doxygen OPTIONAL_COMPONENTS dot)
if(DOXYGEN_FOUND)
set(DOXYGEN_PROJECT_NAME "Data Acquisition System")
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md")
set(DOXYGEN_WARN_NO_PARAMDOC YES)
set(DOXYGEN_GENERATE_QHP YES)
set(DOXYGEN_QCH_FILE "TheName.qch")
set(DOXYGEN_QHP_NAMESPACE org.doxygen.TheName.Project)
set(DOXYGEN_GENERATE_LATEX NO)
set(DOXYGEN_GENERATE_TREEVIEW YES)
#set(DOXYGEN_HIDE_UNDOC_RELATIONS NO)
#set(DOXYGEN_DOT_NUM_THREADS 1)
#set(DOXYGEN_UML_LOOK YES)
#set(DOXYGEN_UML_LIMIT_NUM_FIELDS 50)
#set(DOXYGEN_TEMPLATE_RELATIONS YES)
set(DOXYGEN_DOT_IMAGE_FORMAT svg)
set(DOXYGEN_INTERACTIVE_SVG YES)
#set(DOXYGEN_DOT_GRAPH_MAX_NODES 100)
#set(DOXYGEN_DOT_TRANSPARENT YES)
#set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
doxygen_add_docs(doc ALL
${CMAKE_SOURCE_DIR} ${CMAKE_SOURCE_DIR}/doc/cmake.dox ${CMAKE_SOURCE_DIR}/usb
ALLOW_DUPLICATE_CUSTOM_TARGETS
#USE_STAMP_FILE
COMMENT "Generating doxygen documentation for ${PROJECT_NAME}"
)
# install generated files
#install(
# DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc/html
# TYPE DOC
# OPTIONAL # because available only after "make doc"
#)
else()
message(FATAL_ERROR "Doxygen is needed to build the documentation.")
endif()
add_custom_target(dox ALL
#DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxygen.stamp
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt
)
include(make_documentation)
PARSE_CMAKE_DOCUMENTATION(INCLUDES "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt" EXCLUDES "${CMAKE_CURRENT_BINARY_DIR}/*" )
WRITE_CMAKE_DOCUMENTATION( "${CMAKE_CURRENT_SOURCE_DIR}/cmake.dox" SORTED )
endif()