Robin Mueller
c2bf09d506
This PR introduces the generation of documentation based on this excellent blog post: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/ It combines the tools Sphinx, Doxygen and Breathe to generate good looking HTML documentation conveniently which can be hosted easily. The helper scripts were unified and there is now one helper.py script which can be used to create, build and open both tests and documentation. "./helper.py -h" can be used to get the different options. This PR also contains some smaller fixes which were necessary for the docs to build
67 lines
2.3 KiB
CMake
67 lines
2.3 KiB
CMake
# This is based on this excellent posting provided by Sy:
|
|
# https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
|
|
find_package(Doxygen REQUIRED)
|
|
find_package(Sphinx REQUIRED)
|
|
|
|
get_target_property(LIB_FSFW_PUBLIC_HEADER_DIRS ${LIB_FSFW_NAME} INTERFACE_INCLUDE_DIRECTORIES)
|
|
# TODO: Add HAL as well
|
|
file(GLOB_RECURSE LIB_FSFW_PUBLIC_HEADERS ${PROJECT_SOURCE_DIR}/src/*.h)
|
|
file(GLOB_RECURSE RST_DOC_FILES ${PROJECT_SOURCE_DIR}/docs/*.rst)
|
|
|
|
set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src)
|
|
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
|
|
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
|
|
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
|
|
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
|
|
|
|
# Replace variables inside @@ with the current values
|
|
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
|
|
|
|
# Doxygen won't create this for us
|
|
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
|
|
|
|
# Only regenerate Doxygen when the Doxyfile or public headers change
|
|
add_custom_command(
|
|
OUTPUT ${DOXYGEN_INDEX_FILE}
|
|
DEPENDS ${LIB_FSFW_PUBLIC_HEADERS}
|
|
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
|
|
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
|
|
COMMENT "Generating docs"
|
|
VERBATIM
|
|
)
|
|
|
|
# Nice named target so we can run the job easily
|
|
add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
|
|
|
|
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
|
|
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
|
|
set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
|
|
|
|
# Only regenerate Sphinx when:
|
|
# - Doxygen has rerun
|
|
# - Our doc files have been updated
|
|
# - The Sphinx config has been updated
|
|
add_custom_command(
|
|
OUTPUT ${SPHINX_INDEX_FILE}
|
|
COMMAND
|
|
${SPHINX_EXECUTABLE} -b html
|
|
# Tell Breathe where to find the Doxygen output
|
|
-Dbreathe_projects.fsfw=${DOXYGEN_OUTPUT_DIR}/xml
|
|
${SPHINX_SOURCE} ${SPHINX_BUILD}
|
|
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
|
DEPENDS
|
|
# Other docs files you want to track should go here (or in some variable)
|
|
${RST_DOC_FILES}
|
|
${DOXYGEN_INDEX_FILE}
|
|
MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
|
|
COMMENT "Generating documentation with Sphinx"
|
|
)
|
|
|
|
# Nice named target so we can run the job easily
|
|
add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
|
|
|
|
# Add an install target to install the docs
|
|
include(GNUInstallDirs)
|
|
install(DIRECTORY ${SPHINX_BUILD}
|
|
DESTINATION ${CMAKE_INSTALL_DOCDIR})
|