diff options
| -rw-r--r-- | CMakeLists.txt | 5 | ||||
| -rw-r--r-- | cmake/modules/GtkDoc.cmake | 239 | ||||
| -rw-r--r-- | doc/reference/libical-glib/CMakeLists.txt | 77 | ||||
| -rw-r--r-- | doc/reference/libical-glib/libical-glib-docs.sgml.in (renamed from doc/reference/libical-glib/libical-glib-docs.xml.in) | 0 |
4 files changed, 255 insertions, 66 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index 02af38c4..1a004dab 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -52,6 +52,11 @@ # Requires glib development package v2.20 or higher # Default=true (build the libical-glib interface) # +# -DENABLE_GTK_DOC=[true|false] +# Set to build libical-glib developer documentation +# Requires gtk-doc and ICAL_BUILD_DOCS option to be true. +# Default=true (build gtk-doc developer documentation) +# # -DUSE_32BIT_TIME_T=[true|false] # Set to build using a 32bit time_t (ignored unless building with MSVC on Windows) # Default=false (use the default size of time_t) diff --git a/cmake/modules/GtkDoc.cmake b/cmake/modules/GtkDoc.cmake new file mode 100644 index 00000000..f89b1bf3 --- /dev/null +++ b/cmake/modules/GtkDoc.cmake @@ -0,0 +1,239 @@ +# GtkDoc.cmake +# +# Macros to support develper documentation build from sources with gtk-doc. +# +# Note that every target and dependency should be defined before the macro is +# called, because it uses information from those targets. +# +# add_gtkdoc(_module _namespace _deprecated_guards _srcdirsvar _depsvar _ignoreheadersvar) +# Adds rules to build developer documentation using gtk-doc for some part. +# Arguments: +# _module - the module name, like 'camel'; it expects ${_part}-docs.sgml.in in the CMAKE_CURRENT_SOURCE_DIR +# _namespace - namespace for symbols +# _deprecated_guards - define name, which guards deprecated symbols +# _srcdirsvar - variable with dirs where the source files are located +# _depsvar - a variable with dependencies (targets) +# _ignoreheadersvar - a variable with a set of header files to ignore +# +# It also adds custom target gtkdoc-rebuild-${_module}-sgml to rebuild the sgml.in +# file based on the current sources. + +option(ENABLE_GTK_DOC "Use gtk-doc to build documentation" True) + +if(NOT ENABLE_GTK_DOC) + return() +endif(NOT ENABLE_GTK_DOC) + +find_program(GTKDOC_SCAN gtkdoc-scan) +find_program(GTKDOC_SCANGOBJ gtkdoc-scangobj) +find_program(GTKDOC_MKDB gtkdoc-mkdb) +find_program(GTKDOC_MKHTML gtkdoc-mkhtml) +find_program(GTKDOC_FIXXREF gtkdoc-fixxref) + +if(NOT (GTKDOC_SCAN AND GTKDOC_MKDB AND GTKDOC_MKHTML AND GTKDOC_FIXXREF)) + message(FATAL_ERROR "Cannot find all gtk-doc binaries, install them or use -DENABLE_GTK_DOC=OFF instead") + return() +endif() + +if(NOT TARGET gtkdocs) + add_custom_target(gtkdocs ALL) +endif(NOT TARGET gtkdocs) + +if(NOT TARGET gtkdoc-rebuild-sgmls) + add_custom_target(gtkdoc-rebuild-sgmls) +endif(NOT TARGET gtkdoc-rebuild-sgmls) + +macro(add_gtkdoc _module _namespace _deprecated_guards _srcdirsvar _depsvar _ignoreheadersvar) + configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/${_module}-docs.sgml.in + ${CMAKE_CURRENT_BINARY_DIR}/${_module}-docs.sgml + @ONLY + ) + + set(OUTPUT_DOCDIR ${SHARE_INSTALL_DIR}/gtk-doc/html/${_module}) + + set(_filedeps) + set(_srcdirs) + foreach(_srcdir ${${_srcdirsvar}}) + set(_srcdirs ${_srcdirs} --source-dir="${_srcdir}") + file(GLOB _files ${_srcdir}/*.h* ${_srcdir}/*.c*) + list(APPEND _filedeps ${_files}) + endforeach(_srcdir) + + set(_mkhtml_prefix "") + if(APPLE) + set(_mkhtml_prefix "${CMAKE_COMMAND} -E env XML_CATALOG_FILES=\"/usr/local/etc/xml/catalog\"") + endif(APPLE) + + set(_scangobj_deps) + set(_scangobj_cflags_list) + set(_scangobj_cflags "") + set(_scangobj_ldflags "") + set(_scangobj_ld_lib_dirs "") + + list(APPEND _scangobj_cflags_list -I${INCLUDE_INSTALL_DIR}) + list(APPEND _scangobj_ldflags -L${LIB_INSTALL_DIR}) + + foreach(opt IN LISTS ${_depsvar}) + if(TARGET ${opt}) + set(_target_type) + get_target_property(_target_type ${opt} TYPE) + if((_target_type STREQUAL "STATIC_LIBRARY") OR (_target_type STREQUAL "SHARED_LIBRARY") OR (_target_type STREQUAL "MODULE_LIBRARY")) + set(_compile_options) + set(_link_libraries) + + get_target_property(_compile_options ${opt} COMPILE_OPTIONS) + get_target_property(_link_libraries ${opt} LINK_LIBRARIES) + + list(APPEND _scangobj_cflags_list ${_compile_options}) + list(APPEND _scangobj_deps ${_link_libraries}) + + unset(_compile_options) + unset(_link_libraries) + endif((_target_type STREQUAL "STATIC_LIBRARY") OR (_target_type STREQUAL "SHARED_LIBRARY") OR (_target_type STREQUAL "MODULE_LIBRARY")) + unset(_target_type) + endif(TARGET ${opt}) + + list(APPEND _scangobj_deps ${opt}) + endforeach(opt) + + if(_scangobj_deps) + list(REMOVE_DUPLICATES _scangobj_deps) + endif(_scangobj_deps) + if(_scangobj_cflags_list) + list(REMOVE_DUPLICATES _scangobj_cflags_list) + endif(_scangobj_cflags_list) + + foreach(opt IN LISTS _scangobj_cflags_list) + set(_scangobj_cflags "${_scangobj_cflags} ${opt}") + endforeach(opt) + + foreach(opt IN LISTS _scangobj_deps) + if(TARGET ${opt}) + set(_target_type) + get_target_property(_target_type ${opt} TYPE) + if((_target_type STREQUAL "STATIC_LIBRARY") OR (_target_type STREQUAL "SHARED_LIBRARY") OR (_target_type STREQUAL "MODULE_LIBRARY")) + set(_output_name "") + get_target_property(_output_name ${opt} OUTPUT_NAME) + if(NOT _output_name) + set(_output_name ${opt}) + endif(NOT _output_name) + set(_scangobj_ldflags "${_scangobj_ldflags} -L$<TARGET_FILE_DIR:${opt}> -l${_output_name}") + + if(_target_type STREQUAL "SHARED_LIBRARY" OR (_target_type STREQUAL "MODULE_LIBRARY")) + set(_scangobj_ld_lib_dirs "${_scangobj_ld_lib_dirs}:$<TARGET_FILE_DIR:${opt}>") + endif(_target_type STREQUAL "SHARED_LIBRARY" OR (_target_type STREQUAL "MODULE_LIBRARY")) + unset(_output_name) + endif((_target_type STREQUAL "STATIC_LIBRARY") OR (_target_type STREQUAL "SHARED_LIBRARY") OR (_target_type STREQUAL "MODULE_LIBRARY")) + unset(_target_type) + else(TARGET ${opt}) + set(_scangobj_ldflags "${_scangobj_ldflags} ${opt}") + endif(TARGET ${opt}) + endforeach(opt) + + set(_scangobj_prefix ${CMAKE_COMMAND} -E env LD_LIBRARY_PATH="${_scangobj_ld_lib_dirs}:${LIB_INSTALL_DIR}") + + if(NOT (_scangobj_cflags STREQUAL "")) + set(_scangobj_cflags --cflags "${_scangobj_cflags}") + endif(NOT (_scangobj_cflags STREQUAL "")) + + if(NOT (_scangobj_ldflags STREQUAL "")) + set(_scangobj_ldflags --ldflags "${_scangobj_ldflags}") + endif(NOT (_scangobj_ldflags STREQUAL "")) + + add_custom_command(OUTPUT html/index.html + COMMAND ${GTKDOC_SCAN} + --module=${_module} + --deprecated-guards="${_deprecated_guards}" + --ignore-headers="${${_ignoreheadersvar}}" + --rebuild-sections + --rebuild-types + ${_srcdirs} + + COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}" ${_scangobj_prefix} ${GTKDOC_SCANGOBJ} + --module=${_module} + ${_scangobj_cflags} + ${_scangobj_ldflags} + + COMMAND ${GTKDOC_MKDB} + --module=${_module} + --name-space=${_namespace} + --main-sgml-file="${CMAKE_CURRENT_BINARY_DIR}/${_module}-docs.sgml" + --sgml-mode + --output-format=xml + ${_srcdirs} + + COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/html" + + COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/html" ${_mkhtml_prefix} ${GTKDOC_MKHTML} --path=.. ${_module} ../${_module}-docs.sgml + + COMMAND ${GTKDOC_FIXXREF} + --module=${_module} + --module-dir=html + --extra-dir=.. + --html-dir="${OUTPUT_DOCDIR}" + + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${_module}-docs.sgml" + ${_filedeps} + COMMENT "Generating ${_module} documentation" + ) + + add_custom_target(gtkdoc-${_module} + DEPENDS html/index.html + ) + + if(${_depsvar}) + add_dependencies(gtkdoc-${_module} ${${_depsvar}}) + endif(${_depsvar}) + + add_dependencies(gtkdocs gtkdoc-${_module}) + + install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ + DESTINATION ${OUTPUT_DOCDIR} + ) + + # *************************************** + # sgml.in file rebuild, unconditional + # *************************************** + add_custom_target(gtkdoc-rebuild-${_module}-sgml + COMMAND ${CMAKE_COMMAND} -E remove_directory "${CMAKE_CURRENT_BINARY_DIR}/tmp" + COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/tmp" + + COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/tmp" + ${GTKDOC_SCAN} + --module=${_module} + --deprecated-guards="${_deprecated_guards}" + --ignore-headers="${_ignore_headers}" + --rebuild-sections + --rebuild-types + ${_srcdirs} + + COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}" ${_scangobj_prefix} ${GTKDOC_SCANGOBJ} + --module=${_module} + ${_scangobj_cflags} + ${_scangobj_ldflags} + + COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/tmp" + ${GTKDOC_MKDB} + --module=${_module} + --name-space=${_namespace} + --main-sgml-file="${CMAKE_CURRENT_BINARY_DIR}/tmp/${_module}-docs.sgml" + --sgml-mode + --output-format=xml + ${_srcdirs} + + COMMAND ${CMAKE_COMMAND} -E rename ${CMAKE_CURRENT_BINARY_DIR}/tmp/${_module}-docs.sgml ${CMAKE_CURRENT_SOURCE_DIR}/${_module}-docs.sgml.in + + COMMAND ${CMAKE_COMMAND} -E echo "File '${CMAKE_CURRENT_SOURCE_DIR}/${_module}-docs.sgml.in' overwritten, make sure you replace generated strings with proper content before committing." + ) + + add_dependencies(gtkdoc-rebuild-sgmls gtkdoc-rebuild-${_module}-sgml) + + unset(_scangobj_prefix) + unset(_scangobj_deps) + unset(_scangobj_cflags_list) + unset(_scangobj_cflags) + unset(_scangobj_ldflags) + unset(_scangobj_ld_lib_dirs) +endmacro(add_gtkdoc) diff --git a/doc/reference/libical-glib/CMakeLists.txt b/doc/reference/libical-glib/CMakeLists.txt index 4013d570..e1a6a4eb 100644 --- a/doc/reference/libical-glib/CMakeLists.txt +++ b/doc/reference/libical-glib/CMakeLists.txt @@ -1,12 +1,4 @@ -find_program(GTKDOC_SCAN gtkdoc-scan DOC "a tool to scan header files for public symbols") -find_program(GTKDOC_MKDB gtkdoc-mkdb DOC "a tool to generate docbook files") -find_program(GTKDOC_MKHTML gtkdoc-mkhtml DOC "a tool to generate documentation in html format") -find_program(GTKDOC_FIXXREF gtkdoc-fixxref DOC "a tool to fix cross references in html files") - -if(NOT (GTKDOC_SCAN AND GTKDOC_MKDB AND GTKDOC_MKHTML AND GTKDOC_FIXXREF)) - message(WARNING "Cannot find all gtk-doc binaries, skipping API reference generation for libical-glib") - return() -endif() +include(GtkDoc) # To regenerate libical-glib-docs.xml.in from current sources use these steps: # a) delete ${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml @@ -22,67 +14,20 @@ endif() # e) compare the changes in the file and return back what should be left, # like the replacement of the "[Insert title here]" and the <bookinfo/> content -configure_file( - ${CMAKE_CURRENT_SOURCE_DIR}/libical-glib-docs.xml.in - ${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml - @ONLY -) - -set(OUTPUT_DOCDIR ${SHARE_INSTALL_DIR}/gtk-doc/html/libical-glib) - -add_custom_command(OUTPUT xml/libical-glib-doc.bottom - COMMAND ${GTKDOC_SCAN} --module=libical-glib - --source-dir="${CMAKE_BINARY_DIR}/src/libical-glib" - --deprecated-guards="LIBICAL_GLIB_DISABLE_DEPRECATED" - --ignore-headers=libical-glib-private.h - --rebuild-sections - --rebuild-types +if(ENABLE_GTK_DOC) - COMMAND ${GTKDOC_MKDB} - --module=libical-glib - --name-space=i-cal - --main-sgml-file="${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml" - --xml-mode - --output-format=xml - --source-dir="${CMAKE_BINARY_DIR}/src/libical-glib" - COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/html" - DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml" -) - -if(APPLE) - add_custom_command(OUTPUT html/index.html - COMMAND env XML_CATALOG_FILES="/usr/local/etc/xml/catalog" ${GTKDOC_MKHTML} - --path=.. - libical-glib - ../libical-glib-docs.xml - WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html" - DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml" - "${CMAKE_CURRENT_BINARY_DIR}/xml/libical-glib-doc.bottom" - COMMENT "Generating libical-glib documentation" + set(SOURCEDIRS + ${CMAKE_BINARY_DIR}/src/libical-glib ) -else() - add_custom_command(OUTPUT html/index.html - COMMAND ${GTKDOC_MKHTML} - --path=.. - libical-glib - ../libical-glib-docs.xml - WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html" - DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/libical-glib-docs.xml" - "${CMAKE_CURRENT_BINARY_DIR}/xml/libical-glib-doc.bottom" - COMMENT "Generating libical-glib documentation" + + set(DEPENDENCIES + ical-glib ) -endif() -add_custom_target(documentation ALL - COMMAND ${GTKDOC_FIXXREF} - --module=libical-glib - --module-dir=. - --extra-dir=.. - --html-dir=${OUTPUT_DOCDIR} - DEPENDS html/index.html - COMMENT "Generating libical-glib documentation" + set(IGNORE_HEADERS + libical-glib-private.h ) -add_dependencies(documentation ical-glib) + add_gtkdoc(libical-glib libical-glib "LIBICAL_GLIB_DISABLE_DEPRECATED" SOURCEDIRS DEPENDENCIES IGNORE_HEADERS) -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ DESTINATION ${OUTPUT_DOCDIR}) +endif(ENABLE_GTK_DOC) diff --git a/doc/reference/libical-glib/libical-glib-docs.xml.in b/doc/reference/libical-glib/libical-glib-docs.sgml.in index b202e198..b202e198 100644 --- a/doc/reference/libical-glib/libical-glib-docs.xml.in +++ b/doc/reference/libical-glib/libical-glib-docs.sgml.in |