Browse Source

Make gtk-doc work again

gtk-doc has gained an official CMake module which can fix xrefs.

Meanwhile, our old module has stopped working for whatever reason,
might be that I've botched the LdCategoryView interface somehow.
tags/v0.2.0
Přemysl Janouch 1 year ago
parent
commit
c09acf120c
Signed by: Přemysl Janouch <p@janouch.name> GPG Key ID: A0420B94F92B9493
3 changed files with 13 additions and 381 deletions
  1. 12
    9
      CMakeLists.txt
  2. 0
    371
      cmake/FindGtkDoc.cmake
  3. 1
    1
      liblogdiag/ld-category-view.c

+ 12
- 9
CMakeLists.txt View File

@@ -109,8 +109,8 @@ foreach (file ${project_PO_FILES})
endforeach (file)

# Documentation
find_package (GtkDoc)
set (project_DOC_DIR "${PROJECT_SOURCE_DIR}/docs/reference")
find_package (GtkDoc 1.25)
set (project_DOC_DIR "${PROJECT_BINARY_DIR}/liblogdiag")

# Project source files
set (liblogdiag_SOURCES
@@ -250,13 +250,16 @@ if (BUILD_TESTING)
endif (BUILD_TESTING)

# Generate documentation
if (GTK_DOC_FOUND)
GTK_DOC_RUN (WORKING_DIR ${project_DOC_DIR}
SOURCE_DIRS ${PROJECT_SOURCE_DIR}/liblogdiag
SCANGOBJ liblogdiag ${logdiag_LIBS}
XML ${project_DOC_DIR}/xml --sgml-mode
HTML ${project_DOC_DIR}/html)
endif (GTK_DOC_FOUND)
if (GTKDOC_FOUND)
# FIXME: not our bug but xml/gtkdocentities.ent cannot be passed
target_link_libraries (liblogdiag ${logdiag_LIBS})
gtk_doc_add_module (liblogdiag
SOURCE ${PROJECT_SOURCE_DIR}/liblogdiag
SUFFIXES c h
# The "official" module wants an XML file I don't want to give it
XML ${PROJECT_BINARY_DIR}/liblogdiag/liblogdiag-docs.xml
LIBRARIES liblogdiag)
endif ()

find_package (CppCheck)
GENERATE_CPPCHECK (SOURCES liblogdiag src tests ENABLE_IDS all

+ 0
- 371
cmake/FindGtkDoc.cmake View File

@@ -1,371 +0,0 @@
# - Finding gtk-doc and building documentation
# This module provides the following function:
#
# GTK_DOC_RUN (
# [ALL]
# [MODULE <module-name>]
# [WORKING_DIR <working-dir>]
# SOURCE_DIRS <source-dir> ...
# [IGNORE_FILES <file> ...]
# [SCANGOBJ <library> [<link-libraries> ...]]
# [{SGML | XML} [<mkdb-output-dir> [<mkdb-options>]]
# [HTML <html-output-dir> <backend-options>]]
# )
#
# The function creates a target named <module-name>_gtkdocize
# which will build the documentation as specified by parameters.
#
# ALL - always build the target
# MODULE - the name of the module
# CMAKE_PROJECT_NAME by default
# WORKING_DIR - path to the working directory
# CMAKE_CURRENT_BINARY_DIR by default
# SOURCE_DIRS - documentation sources
# IGNORE_FILES - ignore these files in the process
# SCANGOBJ - build an object hierarchy scanner
# SGML - make SGML output in the spec. directory
# XML - make XML output in the spec. directory
# HTML - make HTML output in the spec. directory
# (requires either SGML or XML)
#
# Also creates these virtual symbolic outputs if appropriate:
# <module-name>_gtkdocize_scan
# <module-name>_gtkdocize_scan_rebuild_types
# <module-name>_gtkdocize_scan_rebuild_sections
# <module-name>_gtkdocize_scan_gobject
# <module-name>_gtkdocize_mkdb
# <module-name>_gtkdocize_mkhtml
#
#

#=============================================================================
# Copyright Přemysl Janouch 2010 - 2011
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
# * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
# OF SUCH DAMAGE.
#=============================================================================

# TODO
# ====
# - Since it doesn't work without the full Unix environment,
# it might be actually proper to use pkg-config
#
# - <module-name>_gtkdocize_fixxref
# - gtkdoc-rebase
# - Content files (included by the main SGML file)
#


find_program (GTK_DOC_SCAN_EXECUTABLE "gtkdoc-scan")
find_program (GTK_DOC_SCANGOBJ_EXECUTABLE "gtkdoc-scangobj")
find_program (GTK_DOC_MKTMPL_EXECUTABLE "gtkdoc-mktmpl")
find_program (GTK_DOC_MKDB_EXECUTABLE "gtkdoc-mkdb")
find_program (GTK_DOC_MKHTML_EXECUTABLE "gtkdoc-mkhtml")
find_program (GTK_DOC_FIXXREF_EXECUTABLE "gtkdoc-fixxref")

mark_as_advanced (GTK_DOC_SCAN_EXECUTABLE GTK_DOC_SCANGOBJ_EXECUTABLE
GTK_DOC_MKTMPL_EXECUTABLE GTK_DOC_MKDB_EXECUTABLE
GTK_DOC_MKHTML_EXECUTABLE GTK_DOC_FIXXREF_EXECUTABLE)

include (FindPackageHandleStandardArgs)
FIND_PACKAGE_HANDLE_STANDARD_ARGS (GTK_DOC DEFAULT_MSG GTK_DOC_SCAN_EXECUTABLE)

include (ProcessArguments)

function (GTK_DOC_RUN)
# Parse arguments given to this function
set (__names ALL MODULE WORKING_DIR SOURCE_DIRS IGNORE_FILES)
set (__need NO NO NO YES NO)
set (__want 0 1 1 1 1)
set (__more NO NO NO YES YES)
set (__skip 0 0 0 0 0)

list (APPEND __names SCANGOBJ SGML XML HTML)
list (APPEND __need NO NO NO NO)
list (APPEND __want 1 0 0 1)
list (APPEND __more YES YES YES YES)
list (APPEND __skip 0 1 0 0)

set (__argv ${ARGV})
PROCESS_ARGUMENTS (__argv __names __need __want __more __skip "_opt_")

# Further process the arguments
if (_opt_all)
set (_all ALL)
else (_opt_all)
set (_all)
endif (_opt_all)

if (_opt_module)
set (_module_name ${_opt_module_param})
else (_opt_module)
set (_module_name ${CMAKE_PROJECT_NAME})
endif (_opt_module)

if (_opt_working_dir)
set (_working_dir ${_opt_working_dir_param})
else (_opt_working_dir)
set (_working_dir ${CMAKE_CURRENT_BINARY_DIR})
endif (_opt_working_dir)

set (_source_dirs)
foreach (_dir ${_opt_source_dirs_param})
list (APPEND _source_dirs "--source-dir" "${_dir}")
endforeach (_dir)

set (_ignores)
if (_opt_ignore_files)
foreach (_file ${_opt_ignore_files_param})
set (_ignores "${_ignores} ${_file}")
endforeach (_file)
string (STRIP "${_ignores}" _ignores)
endif (_opt_ignore_files)

if (_opt_sgml)
set (_mkdb_format "sgml")
set (_mkdb_options "${_opt_sgml_param}")
elseif (_opt_xml)
set (_mkdb_format "xml")
set (_mkdb_options "${_opt_xml_param}")
else (_opt_sgml)
set (_mkdb_format OFF)
endif (_opt_sgml)

if (_mkdb_format)
set (_mkdb_driver ${_working_dir}/${_module_name}-docs.${_mkdb_format})
list (LENGTH _mkdb_options _length)
if (${_length} GREATER 0)
list (GET _mkdb_options 0 _mkdb_output_dir)
list (REMOVE_AT _mkdb_options 0)
else (${_length} GREATER 0)
set (_mkdb_output_dir ${_working_dir}/${_mkdb_format})
endif (${_length} GREATER 0)
endif (_mkdb_format)

# The basic target name
set (_target_name ${_module_name}_gtkdocize)

# Scan the source files
set (_scan_target_base
# These files are created if they don't exist
# ${_working_dir}/${_module_name}.types
# ${_working_dir}/${_module_name}-sections.txt
# ${_working_dir}/${_module_name}-overrides.txt
${_working_dir}/${_module_name}-decl.txt
${_working_dir}/${_module_name}-decl-list.txt
COMMAND ${GTK_DOC_SCAN_EXECUTABLE}
--module=${_module_name}
${_source_dirs} "--ignore-headers=${_ignores}"
--output-dir=${_working_dir})
add_custom_command (
OUTPUT ${_target_name}_scan
${_scan_target_base}
COMMENT "Calling gtkdoc-scan" VERBATIM)

# Special target to force rebuild of ${_module_name}.types
add_custom_command (
OUTPUT ${_target_name}_scan_rebuild_types
${_scan_target_base} --rebuild-types
COMMENT "Calling gtkdoc-scan to rebuild types" VERBATIM)
add_custom_target (${_target_name}_rebuild_types
DEPENDS ${_target_name}_scan_rebuild_types)

# Special target to force rebuild of ${_module_name}-sections.txt
add_custom_command (
OUTPUT ${_target_name}_scan_rebuild_sections
${_scan_target_base} --rebuild-sections
COMMENT "Calling gtkdoc-scan to rebuild sections" VERBATIM)
add_custom_target (${_target_name}_rebuild_sections
DEPENDS ${_target_name}_scan_rebuild_sections)

set_source_files_properties (
${_target_name}_scan
${_target_name}_scan_rebuild_types
${_target_name}_scan_rebuild_sections
PROPERTIES SYMBOLIC TRUE)
set (_top_output ${_target_name}_scan)

# Scan the object hierarchy
# This is a terrible hack, but there's no other way around.
if (_opt_scangobj)
# Put all include directories into CFLAGS
set (_cflags)
get_directory_property (_include_dirs INCLUDE_DIRECTORIES)
foreach (_dir ${_include_dirs})
set (_cflags "${_cflags} -I${_dir}")
endforeach (_dir)

# Put all libraries to LDFLAGS
set (_ldflags "-L${CMAKE_CURRENT_BINARY_DIR}")
set (_lib_depends)
set (_lib_dir_used)
foreach (_lib ${_opt_scangobj_param} ${CMAKE_STANDARD_LIBRARIES})
get_filename_component (_lib_dir ${_lib} PATH)
get_filename_component (_lib_name ${_lib} NAME)

if (TARGET ${_lib_name})
get_target_property (_lib_output_name ${_lib_name} OUTPUT_NAME)
if (_lib_output_name)
set (_lib_name ${_lib_output_name})
endif (_lib_output_name)
list (APPEND _lib_depends ${_lib_name})
else (TARGET ${_lib_name})
list (FIND _lib_dir_used "${_lib_dir}" _lib_dir_found)
if (_lib_dir AND _lib_dir_found EQUAL "-1")
set (_ldflags "${_ldflags} -L${_lib_dir}")
list (APPEND _lib_dir_used ${_lib_dir})
endif (_lib_dir AND _lib_dir_found EQUAL "-1")

string (REGEX REPLACE "^${CMAKE_SHARED_LIBRARY_PREFIX}" ""
_lib_name "${_lib_name}")
string (REGEX REPLACE "${CMAKE_SHARED_LIBRARY_SUFFIX}\$" ""
_lib_name "${_lib_name}")
endif (TARGET ${_lib_name})

set (_ldflags "${_ldflags} -l${_lib_name}")
endforeach (_lib)

add_custom_command (
OUTPUT ${_target_name}_scan_gobject
${_working_dir}/${_module_name}.signals
${_working_dir}/${_module_name}.hierarchy
${_working_dir}/${_module_name}.interfaces
${_working_dir}/${_module_name}.prerequisites
${_working_dir}/${_module_name}.args
COMMAND "CC=${CMAKE_C_COMPILER}" "CFLAGS=${_cflags}"
"LD=${CMAKE_C_COMPILER}" "LDFLAGS=${_ldflags}"
"RUN=" ${GTK_DOC_SCANGOBJ_EXECUTABLE}
--module=${_module_name} --output-dir=${_working_dir}
DEPENDS ${_top_output} ${_lib_depends}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Calling gtkdoc-scangobj")

set_source_files_properties (${_target_name}_scan_gobject
PROPERTIES SYMBOLIC TRUE)
set (_top_output ${_target_name}_scan_gobject)
endif (_opt_scangobj)

# Create XML or SGML files
if (_mkdb_format)
add_custom_command (
OUTPUT ${_target_name}_mkdb
${_mkdb_output_dir}
${_working_dir}/sgml.stamp
${_working_dir}/${_module_name}-undeclared.txt
${_working_dir}/${_module_name}-undocumented.txt
${_working_dir}/${_module_name}-unused.txt
# --outputallsymbols --outputsymbolswithoutsince
# ${_working_dir}/${_module_name}-symbols.txt
# ${_working_dir}/${_module_name}-nosince.txt
COMMAND ${CMAKE_COMMAND} -E remove_directory ${_mkdb_output_dir}
COMMAND ${GTK_DOC_MKDB_EXECUTABLE}
--module=${_module_name}
${_source_dirs} "--ignore-files=${_ignores}"
--output-format=${_mkdb_format}
--output-dir=${_mkdb_output_dir}
${_mkdb_options} --main-sgml-file=${_mkdb_driver}
DEPENDS ${_top_output}
WORKING_DIRECTORY ${_working_dir}
COMMENT "Calling gtkdoc-mkdb" VERBATIM)

set_source_files_properties (${_target_name}_mkdb
PROPERTIES SYMBOLIC TRUE)
set (_top_output ${_target_name}_mkdb)
endif (_mkdb_format)

# Create HTML documentation
if (_opt_html)
if (NOT _mkdb_format)
message (FATAL_ERROR "Given HTML but neither XML nor SGML")
endif (NOT _mkdb_format)

list (GET _opt_html_param 0 _html_output_dir)
list (REMOVE_AT _opt_html_param 0)

add_custom_command (
OUTPUT ${_target_name}_mkhtml
${_html_output_dir}/../html.stamp
# We probably don't want this to be removed either
# ${_html_output_dir}
COMMAND ${CMAKE_COMMAND} -E remove_directory ${_html_output_dir}
COMMAND ${CMAKE_COMMAND} -E make_directory ${_html_output_dir}
COMMAND ${CMAKE_COMMAND} -E chdir ${_html_output_dir}
${GTK_DOC_MKHTML_EXECUTABLE}
${_module_name} ${_mkdb_driver} ${_opt_html_param}
DEPENDS ${_top_output}
COMMENT "Calling gtkdoc-mkhtml" VERBATIM)

set_source_files_properties (${_target_name}_mkhtml
PROPERTIES SYMBOLIC TRUE)
set (_top_output ${_target_name}_mkhtml)
endif (_opt_html)

# gtkdoc-fixxref
# ? copy ${_html_output_dir} to CMAKE_BINARY_DIR,
# run gtkdoc-fixxref in there and install the directory
# -> FIXXREF <output-dir> [INSTALL]
#
#? set (_fixxref_dir ${CMAKE_CURRENT_BINARY_DIR}/html-fixxref)
# add_custom_command (
# OUTPUT ${_target_name}_fixxref
#? ${_fixxref_dir}
#? COMMAND ${CMAKE_COMMAND} -E remove_directory ${_fixxref_dir}
#? COMMAND ${CMAKE_COMMAND} -E copy_directory
#? ${_html_output_dir} ${_fixxref_dir}
# COMMAND ${GTK_DOC_FIXXREF_EXECUTABLE}
# --module=${_module_name}
# --module-dir=${_html_output_dir}
#? --module-dir=${_fixxref_dir}
# DEPENDS ${_html_output_dir}
# WORKING_DIRECTORY ${_working_dir}
# COMMENT "Calling gtkdoc-fixxref" VERBATIM)
#? install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html-fixxref/
#? DESTINATION share/gtk-doc/html/${_module_name})
#& COMPONENT docs) -- see CPack component install

# gtkdoc-rebase -- how to do this?
#
# Probably omit this because source tarball cannot be hooked
# to do some action before.
# -> Custom dist target?
# add_custom_target(dist COMMAND ${CMAKE_MAKE_PROGRAM} package_source)
# -> ${_html_output_dir} could contain online links by default,
# then it could be copied to binary dir and rebased to relative
# * Looks like a very good idea, can work even without gtk-doc
# -> Or it can be first xreffed in the binary dir and then
# converted to online links in ${_html_output_dir}
# * Which one of those should be installed?
# The one in the binary directory or should the
# ${_html_output_dir} be rebased?
# * A rebasing custom command may create the binary directory
# if it doesn't exist
#
# When creating the source tarball for distribution,
# gtkdoc-rebase turns all external links into web-links.
# When installing distributed (pregenerated) docs the same
# application will try to turn links back to local links
# (where those docs are installed).

add_custom_target (${_target_name} ${_all}
DEPENDS ${_top_output})
endfunction (GTK_DOC_RUN)



+ 1
- 1
liblogdiag/ld-category-view.c View File

@@ -71,7 +71,7 @@ ld_category_view_default_init (LdCategoryViewInterface *iface)

/**
* ld_category_view_set_category:
* @self: an #LdCategorylView object.
* @self: an #LdCategoryView object.
* @category: the #LdCategory to be assigned to the view.
*
* Assign an #LdCategory object to the view.

Loading…
Cancel
Save