Commit 59ffabfe authored by Alex Turbov's avatar Alex Turbov
Browse files

Improve Doxygen support

Except Graphviz's `dot` Doxygen may use few other utilities like
`mscgen` (Message Sequence Chart) and `dia` (Diagram Editor).

Now this module allows to manage Doxygen settings from `CMakeLists.txt`
and forget about `Doxyfile`s. Also it provides a helper function
to add a target to generate documentation: `doxygen_add_docs`.

Implement code review notes:

- Introduce `COMPONENTS` to find: `dot`, `mscgen` and `dia`;
- Deprecate variables `DOXYGEN_SKIP_DOT`, `DOXYGEN_EXECUTABLE`,
  `DOXYGEN_DOT_EXECUTABLE`, `DOXYGEN_DOT_FOUND` in favour of
  `doxygen_add_docs ` usage instead;
- Properly handle paths to found tools in Windows;
- Prevent adding a custom target if Doxygen was not really found;
- Introduce exported (executable) targets for found components.

Co-Author: Craig Scott <craig.scott@crascit.com>
parent ae5f98a5
doxygen-improvements
--------------------
* The :module:`FindDoxygen` module learned to control Doxygen behavior using
CMake variables and generate documentation via the newly added
:command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``)
is automatically generated and doxygen is run as part of a custom target.
A number of doxygen-related variables have been deprecated. Additional
components can be specified to find optional tools: ``dot``, ``mscgen``
and ``dia``.
This diff is collapsed.
......@@ -1385,6 +1385,10 @@ ${CMake_BINARY_DIR}/bin/cmake -DDIR=dev -P ${CMake_SOURCE_DIR}/Utilities/Release
add_subdirectory(FindBZip2)
endif()
if(CMake_TEST_FindDoxygen)
add_subdirectory(FindDoxygen)
endif()
if(CMake_TEST_FindGSL)
add_subdirectory(FindGSL)
endif()
......
add_test(NAME FindDoxygen.SimpleTest COMMAND
${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
--build-and-test
"${CMake_SOURCE_DIR}/Tests/FindDoxygen/SimpleTest"
"${CMake_BINARY_DIR}/Tests/FindDoxygen/SimpleTest"
--build-target allDocTargets
${build_generator_args}
--build-options ${build_options}
)
if(CMake_TEST_FindDoxygen_Dot)
add_test(NAME FindDoxygen.DotComponentTest COMMAND
${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
--build-and-test
"${CMake_SOURCE_DIR}/Tests/FindDoxygen/DotComponentTestTest"
"${CMake_BINARY_DIR}/Tests/FindDoxygen/DotComponentTestTest"
${build_generator_args}
--build-options ${build_options}
)
endif()
cmake_minimum_required(VERSION 3.8)
project(TestFindDoxygenDot VERSION 1.0 LANGUAGES NONE)
# Testing a new signature w/ components
find_package(Doxygen REQUIRED COMPONENTS dot)
# No backwards compatibility expected when component form is used
if(TARGET Doxygen::doxygen)
if(DOXYGEN)
message(FATAL_ERROR "DOXYGEN unexpectedly defined with component form")
endif()
else()
message(FATAL_ERROR "Import target Doxygen::doxygen not defined")
endif()
if(NOT TARGET Doxygen::dot)
message(FATAL_ERROR "Import target Doxygen::dot not defined")
endif()
cmake_minimum_required(VERSION 3.8)
project(TestFindDoxygen VERSION 1.0 LANGUAGES NONE)
# Testing backward compatible signature
find_package(Doxygen REQUIRED)
if(TARGET Doxygen::doxygen)
# Check backward compatibility
if(NOT DOXYGEN_EXECUTABLE)
message(FATAL_ERROR "Backward compatibility broken: DOXYGEN_EXECUTABLE not set")
endif()
if(NOT DOXYGEN)
message(FATAL_ERROR "Backward compatibility broken: DOXYGEN not set")
endif()
# Check presence of expected generated files
foreach(file CMakeDoxyfile.in CMakeDoxygenDefaults.cmake)
if(NOT EXISTS "${PROJECT_BINARY_DIR}/${file}")
message(FATAL_ERROR "Missing generated file: ${file}")
endif()
endforeach()
else()
message(FATAL_ERROR "Import target Doxygen::doxygen not defined")
endif()
doxygen_add_docs(docsNoArgs)
if(NOT EXISTS "${PROJECT_BINARY_DIR}/Doxyfile.docsNoArgs")
message(FATAL_ERROR "Missing generated file: Doxyfile.docsNoArgs")
endif()
if(NOT TARGET docsNoArgs)
message(FATAL_ERROR "Target docsNoArgs not created")
endif()
configure_file(spaces_in_name.cpp.in "spaces in name.cpp" COPYONLY)
doxygen_add_docs(docsWithArgs
"${CMAKE_CURRENT_BINARY_DIR}/spaces in name.cpp"
main.cpp
)
if(NOT EXISTS "${PROJECT_BINARY_DIR}/Doxyfile.docsWithArgs")
message(FATAL_ERROR "Missing generated file: Doxyfile.docsWithArgs")
endif()
if(NOT TARGET docsWithArgs)
message(FATAL_ERROR "Target docsWithArgs not created")
endif()
# Note that CMake inserts at least one entry into SOURCES when a COMMAND or
# DEPENDS option is given to add_custom_target(), so rather than looking for an
# exact match, we only verify that the files we expect to be there are present
get_target_property(srcList docsWithArgs SOURCES)
set(expectedList
"${CMAKE_CURRENT_BINARY_DIR}/spaces in name.cpp"
"${CMAKE_CURRENT_SOURCE_DIR}/main.cpp"
)
foreach(f IN LISTS expectedList)
if(NOT f IN_LIST srcList)
message(FATAL_ERROR "SOURCES missing file: ${f}")
endif()
endforeach()
add_custom_target(allDocTargets)
add_dependencies(allDocTargets docsNoArgs docsWithArgs)
/**
* \file
* \brief One C++ file w/ sample Doxygen comment just to produce any docs...
*/
/**
* \file
* \brief This file name contains spaces
*/
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment