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.
Přemysl Janouch 5 months 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})
109 109
 endforeach (file)
110 110
 
111 111
 # Documentation
112
-find_package (GtkDoc)
113
-set (project_DOC_DIR "${PROJECT_SOURCE_DIR}/docs/reference")
112
+find_package (GtkDoc 1.25)
113
+set (project_DOC_DIR "${PROJECT_BINARY_DIR}/liblogdiag")
114 114
 
115 115
 # Project source files
116 116
 set (liblogdiag_SOURCES
@@ -250,13 +250,16 @@ if (BUILD_TESTING)
250 250
 endif (BUILD_TESTING)
251 251
 
252 252
 # Generate documentation
253
-if (GTK_DOC_FOUND)
254
-	GTK_DOC_RUN (WORKING_DIR ${project_DOC_DIR}
255
-		SOURCE_DIRS ${PROJECT_SOURCE_DIR}/liblogdiag
256
-		SCANGOBJ liblogdiag ${logdiag_LIBS}
257
-		XML ${project_DOC_DIR}/xml --sgml-mode
258
-		HTML ${project_DOC_DIR}/html)
259
-endif (GTK_DOC_FOUND)
253
+if (GTKDOC_FOUND)
254
+	# FIXME: not our bug but xml/gtkdocentities.ent cannot be passed
255
+	target_link_libraries (liblogdiag ${logdiag_LIBS})
256
+	gtk_doc_add_module (liblogdiag
257
+		SOURCE ${PROJECT_SOURCE_DIR}/liblogdiag
258
+		SUFFIXES c h
259
+		# The "official" module wants an XML file I don't want to give it
260
+		XML ${PROJECT_BINARY_DIR}/liblogdiag/liblogdiag-docs.xml
261
+		LIBRARIES liblogdiag)
262
+endif ()
260 263
 
261 264
 find_package (CppCheck)
262 265
 GENERATE_CPPCHECK (SOURCES liblogdiag src tests ENABLE_IDS all

+ 0
- 371
cmake/FindGtkDoc.cmake View File

@@ -1,371 +0,0 @@
1
-# - Finding gtk-doc and building documentation
2
-# This module provides the following function:
3
-#
4
-# GTK_DOC_RUN (
5
-#   [ALL]
6
-#   [MODULE <module-name>]
7
-#   [WORKING_DIR <working-dir>]
8
-#   SOURCE_DIRS <source-dir> ...
9
-#   [IGNORE_FILES <file> ...]
10
-#   [SCANGOBJ <library> [<link-libraries> ...]]
11
-#   [{SGML | XML} [<mkdb-output-dir> [<mkdb-options>]]
12
-#   [HTML <html-output-dir> <backend-options>]]
13
-# )
14
-#
15
-# The function creates a target named <module-name>_gtkdocize
16
-# which will build the documentation as specified by parameters.
17
-#
18
-#   ALL          - always build the target
19
-#   MODULE       - the name of the module
20
-#                  CMAKE_PROJECT_NAME by default
21
-#   WORKING_DIR  - path to the working directory
22
-#                  CMAKE_CURRENT_BINARY_DIR by default
23
-#   SOURCE_DIRS  - documentation sources
24
-#   IGNORE_FILES - ignore these files in the process
25
-#   SCANGOBJ     - build an object hierarchy scanner
26
-#   SGML         - make SGML output in the spec. directory
27
-#   XML          - make XML output in the spec. directory
28
-#   HTML         - make HTML output in the spec. directory
29
-#                  (requires either SGML or XML)
30
-#
31
-# Also creates these virtual symbolic outputs if appropriate:
32
-#   <module-name>_gtkdocize_scan
33
-#   <module-name>_gtkdocize_scan_rebuild_types
34
-#   <module-name>_gtkdocize_scan_rebuild_sections
35
-#   <module-name>_gtkdocize_scan_gobject
36
-#   <module-name>_gtkdocize_mkdb
37
-#   <module-name>_gtkdocize_mkhtml
38
-#
39
-#
40
-
41
-#=============================================================================
42
-# Copyright Přemysl Janouch 2010 - 2011
43
-# All rights reserved.
44
-#
45
-# Redistribution and use in source and binary forms, with or without
46
-# modification, are permitted provided that the following conditions are met:
47
-#     * Redistributions of source code must retain the above copyright
48
-#       notice, this list of conditions and the following disclaimer.
49
-#     * Redistributions in binary form must reproduce the above copyright
50
-#       notice, this list of conditions and the following disclaimer in the
51
-#       documentation and/or other materials provided with the distribution.
52
-#
53
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
54
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
55
-# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
56
-# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE
57
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
58
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
59
-# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
60
-# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
61
-# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
62
-# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
63
-# OF SUCH DAMAGE.
64
-#=============================================================================
65
-
66
-# TODO
67
-# ====
68
-#  - Since it doesn't work without the full Unix environment,
69
-#    it might be actually proper to use pkg-config
70
-#
71
-#  - <module-name>_gtkdocize_fixxref
72
-#  - gtkdoc-rebase
73
-#  - Content files (included by the main SGML file)
74
-#
75
-
76
-
77
-find_program (GTK_DOC_SCAN_EXECUTABLE "gtkdoc-scan")
78
-find_program (GTK_DOC_SCANGOBJ_EXECUTABLE "gtkdoc-scangobj")
79
-find_program (GTK_DOC_MKTMPL_EXECUTABLE "gtkdoc-mktmpl")
80
-find_program (GTK_DOC_MKDB_EXECUTABLE "gtkdoc-mkdb")
81
-find_program (GTK_DOC_MKHTML_EXECUTABLE "gtkdoc-mkhtml")
82
-find_program (GTK_DOC_FIXXREF_EXECUTABLE "gtkdoc-fixxref")
83
-
84
-mark_as_advanced (GTK_DOC_SCAN_EXECUTABLE GTK_DOC_SCANGOBJ_EXECUTABLE
85
-	GTK_DOC_MKTMPL_EXECUTABLE GTK_DOC_MKDB_EXECUTABLE
86
-	GTK_DOC_MKHTML_EXECUTABLE GTK_DOC_FIXXREF_EXECUTABLE)
87
-
88
-include (FindPackageHandleStandardArgs)
89
-FIND_PACKAGE_HANDLE_STANDARD_ARGS (GTK_DOC DEFAULT_MSG GTK_DOC_SCAN_EXECUTABLE)
90
-
91
-include (ProcessArguments)
92
-
93
-function (GTK_DOC_RUN)
94
-	# Parse arguments given to this function
95
-	set (__names  ALL  MODULE  WORKING_DIR  SOURCE_DIRS  IGNORE_FILES)
96
-	set (__need   NO   NO      NO           YES          NO)
97
-	set (__want   0    1       1            1            1)
98
-	set (__more   NO   NO      NO           YES          YES)
99
-	set (__skip   0    0       0            0            0)
100
-
101
-	list (APPEND __names  SCANGOBJ  SGML  XML  HTML)
102
-	list (APPEND __need   NO        NO    NO   NO)
103
-	list (APPEND __want   1         0     0    1)
104
-	list (APPEND __more   YES       YES   YES  YES)
105
-	list (APPEND __skip   0         1     0    0)
106
-
107
-	set (__argv ${ARGV})
108
-	PROCESS_ARGUMENTS (__argv __names __need __want __more __skip "_opt_")
109
-
110
-	# Further process the arguments
111
-	if (_opt_all)
112
-		set (_all ALL)
113
-	else (_opt_all)
114
-		set (_all)
115
-	endif (_opt_all)
116
-
117
-	if (_opt_module)
118
-		set (_module_name ${_opt_module_param})
119
-	else (_opt_module)
120
-		set (_module_name ${CMAKE_PROJECT_NAME})
121
-	endif (_opt_module)
122
-
123
-	if (_opt_working_dir)
124
-		set (_working_dir ${_opt_working_dir_param})
125
-	else (_opt_working_dir)
126
-		set (_working_dir ${CMAKE_CURRENT_BINARY_DIR})
127
-	endif (_opt_working_dir)
128
-
129
-	set (_source_dirs)
130
-	foreach (_dir ${_opt_source_dirs_param})
131
-		list (APPEND _source_dirs "--source-dir" "${_dir}")
132
-	endforeach (_dir)
133
-
134
-	set (_ignores)
135
-	if (_opt_ignore_files)
136
-		foreach (_file ${_opt_ignore_files_param})
137
-			set (_ignores "${_ignores} ${_file}")
138
-		endforeach (_file)
139
-		string (STRIP "${_ignores}" _ignores)
140
-	endif (_opt_ignore_files)
141
-
142
-	if (_opt_sgml)
143
-		set (_mkdb_format "sgml")
144
-		set (_mkdb_options "${_opt_sgml_param}")
145
-	elseif (_opt_xml)
146
-		set (_mkdb_format "xml")
147
-		set (_mkdb_options "${_opt_xml_param}")
148
-	else (_opt_sgml)
149
-		set (_mkdb_format OFF)
150
-	endif (_opt_sgml)
151
-
152
-	if (_mkdb_format)
153
-		set (_mkdb_driver ${_working_dir}/${_module_name}-docs.${_mkdb_format})
154
-		list (LENGTH _mkdb_options _length)
155
-		if (${_length} GREATER 0)
156
-			list (GET _mkdb_options 0 _mkdb_output_dir)
157
-			list (REMOVE_AT _mkdb_options 0)
158
-		else (${_length} GREATER 0)
159
-			set (_mkdb_output_dir ${_working_dir}/${_mkdb_format})
160
-		endif (${_length} GREATER 0)
161
-	endif (_mkdb_format)
162
-
163
-	# The basic target name
164
-	set (_target_name ${_module_name}_gtkdocize)
165
-
166
-	# Scan the source files
167
-	set (_scan_target_base
168
-	# These files are created if they don't exist
169
-	#	        ${_working_dir}/${_module_name}.types
170
-	#	        ${_working_dir}/${_module_name}-sections.txt
171
-	#	        ${_working_dir}/${_module_name}-overrides.txt
172
-		        ${_working_dir}/${_module_name}-decl.txt
173
-		        ${_working_dir}/${_module_name}-decl-list.txt
174
-		COMMAND ${GTK_DOC_SCAN_EXECUTABLE}
175
-		        --module=${_module_name}
176
-		        ${_source_dirs} "--ignore-headers=${_ignores}"
177
-		        --output-dir=${_working_dir})
178
-	add_custom_command (
179
-		OUTPUT ${_target_name}_scan
180
-		${_scan_target_base}
181
-		COMMENT "Calling gtkdoc-scan" VERBATIM)
182
-
183
-	# Special target to force rebuild of ${_module_name}.types
184
-	add_custom_command (
185
-		OUTPUT ${_target_name}_scan_rebuild_types
186
-		${_scan_target_base} --rebuild-types
187
-		COMMENT "Calling gtkdoc-scan to rebuild types" VERBATIM)
188
-	add_custom_target (${_target_name}_rebuild_types
189
-		DEPENDS ${_target_name}_scan_rebuild_types)
190
-
191
-	# Special target to force rebuild of ${_module_name}-sections.txt
192
-	add_custom_command (
193
-		OUTPUT ${_target_name}_scan_rebuild_sections
194
-		${_scan_target_base} --rebuild-sections
195
-		COMMENT "Calling gtkdoc-scan to rebuild sections" VERBATIM)
196
-	add_custom_target (${_target_name}_rebuild_sections
197
-		DEPENDS ${_target_name}_scan_rebuild_sections)
198
-
199
-	set_source_files_properties (
200
-		${_target_name}_scan
201
-		${_target_name}_scan_rebuild_types
202
-		${_target_name}_scan_rebuild_sections
203
-		PROPERTIES SYMBOLIC TRUE)
204
-	set (_top_output ${_target_name}_scan)
205
-
206
-	# Scan the object hierarchy
207
-	# This is a terrible hack, but there's no other way around.
208
-	if (_opt_scangobj)
209
-		# Put all include directories into CFLAGS
210
-		set (_cflags)
211
-		get_directory_property (_include_dirs INCLUDE_DIRECTORIES)
212
-		foreach (_dir ${_include_dirs})
213
-			set (_cflags "${_cflags} -I${_dir}")
214
-		endforeach (_dir)
215
-
216
-		# Put all libraries to LDFLAGS
217
-		set (_ldflags "-L${CMAKE_CURRENT_BINARY_DIR}")
218
-		set (_lib_depends)
219
-		set (_lib_dir_used)
220
-		foreach (_lib ${_opt_scangobj_param} ${CMAKE_STANDARD_LIBRARIES})
221
-			get_filename_component (_lib_dir ${_lib} PATH)
222
-			get_filename_component (_lib_name ${_lib} NAME)
223
-
224
-			if (TARGET ${_lib_name})
225
-				get_target_property (_lib_output_name ${_lib_name} OUTPUT_NAME)
226
-				if (_lib_output_name)
227
-					set (_lib_name ${_lib_output_name})
228
-				endif (_lib_output_name)
229
-				list (APPEND _lib_depends ${_lib_name})
230
-			else (TARGET ${_lib_name})
231
-				list (FIND _lib_dir_used "${_lib_dir}" _lib_dir_found)
232
-				if (_lib_dir AND _lib_dir_found EQUAL "-1")
233
-					set (_ldflags "${_ldflags} -L${_lib_dir}")
234
-					list (APPEND _lib_dir_used ${_lib_dir})
235
-				endif (_lib_dir AND _lib_dir_found EQUAL "-1")
236
-
237
-				string (REGEX REPLACE "^${CMAKE_SHARED_LIBRARY_PREFIX}" ""
238
-					_lib_name "${_lib_name}")
239
-				string (REGEX REPLACE "${CMAKE_SHARED_LIBRARY_SUFFIX}\$" ""
240
-					_lib_name "${_lib_name}")
241
-			endif (TARGET ${_lib_name})
242
-
243
-			set (_ldflags "${_ldflags} -l${_lib_name}")
244
-		endforeach (_lib)
245
-
246
-		add_custom_command (
247
-			OUTPUT ${_target_name}_scan_gobject
248
-			       ${_working_dir}/${_module_name}.signals
249
-			       ${_working_dir}/${_module_name}.hierarchy
250
-			       ${_working_dir}/${_module_name}.interfaces
251
-			       ${_working_dir}/${_module_name}.prerequisites
252
-			       ${_working_dir}/${_module_name}.args
253
-			COMMAND "CC=${CMAKE_C_COMPILER}" "CFLAGS=${_cflags}"
254
-			        "LD=${CMAKE_C_COMPILER}" "LDFLAGS=${_ldflags}"
255
-			        "RUN=" ${GTK_DOC_SCANGOBJ_EXECUTABLE}
256
-			        --module=${_module_name} --output-dir=${_working_dir}
257
-			DEPENDS ${_top_output} ${_lib_depends}
258
-			WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
259
-			COMMENT "Calling gtkdoc-scangobj")
260
-
261
-		set_source_files_properties (${_target_name}_scan_gobject
262
-			PROPERTIES SYMBOLIC TRUE)
263
-		set (_top_output ${_target_name}_scan_gobject)
264
-	endif (_opt_scangobj)
265
-
266
-	# Create XML or SGML files
267
-	if (_mkdb_format)
268
-		add_custom_command (
269
-			OUTPUT ${_target_name}_mkdb
270
-			       ${_mkdb_output_dir}
271
-			       ${_working_dir}/sgml.stamp
272
-			       ${_working_dir}/${_module_name}-undeclared.txt
273
-			       ${_working_dir}/${_module_name}-undocumented.txt
274
-			       ${_working_dir}/${_module_name}-unused.txt
275
-		# --outputallsymbols --outputsymbolswithoutsince
276
-		#	       ${_working_dir}/${_module_name}-symbols.txt
277
-		#	       ${_working_dir}/${_module_name}-nosince.txt
278
-			COMMAND ${CMAKE_COMMAND} -E remove_directory ${_mkdb_output_dir}
279
-			COMMAND ${GTK_DOC_MKDB_EXECUTABLE}
280
-			        --module=${_module_name}
281
-			        ${_source_dirs} "--ignore-files=${_ignores}"
282
-			        --output-format=${_mkdb_format}
283
-			        --output-dir=${_mkdb_output_dir}
284
-			        ${_mkdb_options} --main-sgml-file=${_mkdb_driver}
285
-			DEPENDS ${_top_output}
286
-			WORKING_DIRECTORY ${_working_dir}
287
-			COMMENT "Calling gtkdoc-mkdb" VERBATIM)
288
-
289
-		set_source_files_properties (${_target_name}_mkdb
290
-			PROPERTIES SYMBOLIC TRUE)
291
-		set (_top_output ${_target_name}_mkdb)
292
-	endif (_mkdb_format)
293
-
294
-	# Create HTML documentation
295
-	if (_opt_html)
296
-		if (NOT _mkdb_format)
297
-			message (FATAL_ERROR "Given HTML but neither XML nor SGML")
298
-		endif (NOT _mkdb_format)
299
-
300
-		list (GET _opt_html_param 0 _html_output_dir)
301
-		list (REMOVE_AT _opt_html_param 0)
302
-
303
-		add_custom_command (
304
-			OUTPUT ${_target_name}_mkhtml
305
-			       ${_html_output_dir}/../html.stamp
306
-		# We probably don't want this to be removed either
307
-		#	       ${_html_output_dir}
308
-			COMMAND ${CMAKE_COMMAND} -E remove_directory ${_html_output_dir}
309
-			COMMAND ${CMAKE_COMMAND} -E make_directory ${_html_output_dir}
310
-			COMMAND ${CMAKE_COMMAND} -E chdir ${_html_output_dir}
311
-			        ${GTK_DOC_MKHTML_EXECUTABLE}
312
-			        ${_module_name} ${_mkdb_driver} ${_opt_html_param}
313
-			DEPENDS ${_top_output}
314
-			COMMENT "Calling gtkdoc-mkhtml" VERBATIM)
315
-
316
-		set_source_files_properties (${_target_name}_mkhtml
317
-			PROPERTIES SYMBOLIC TRUE)
318
-		set (_top_output ${_target_name}_mkhtml)
319
-	endif (_opt_html)
320
-
321
-	# gtkdoc-fixxref
322
-	#   ? copy ${_html_output_dir} to CMAKE_BINARY_DIR,
323
-	#     run gtkdoc-fixxref in there and install the directory
324
-	#      -> FIXXREF <output-dir> [INSTALL]
325
-	#
326
-	#? set (_fixxref_dir ${CMAKE_CURRENT_BINARY_DIR}/html-fixxref)
327
-	# add_custom_command (
328
-	#	OUTPUT ${_target_name}_fixxref
329
-	#?	       ${_fixxref_dir}
330
-	#?	COMMAND ${CMAKE_COMMAND} -E remove_directory ${_fixxref_dir}
331
-	#?	COMMAND ${CMAKE_COMMAND} -E copy_directory
332
-	#?	        ${_html_output_dir} ${_fixxref_dir}
333
-	#	COMMAND ${GTK_DOC_FIXXREF_EXECUTABLE}
334
-	#	        --module=${_module_name}
335
-	#	        --module-dir=${_html_output_dir}
336
-	#?	        --module-dir=${_fixxref_dir}
337
-	#	DEPENDS ${_html_output_dir}
338
-	#	WORKING_DIRECTORY ${_working_dir}
339
-	#	COMMENT "Calling gtkdoc-fixxref" VERBATIM)
340
-	#? install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html-fixxref/
341
-	#?          DESTINATION share/gtk-doc/html/${_module_name})
342
-	#&          COMPONENT docs) -- see CPack component install
343
-
344
-	# gtkdoc-rebase -- how to do this?
345
-	#
346
-	# Probably omit this because source tarball cannot be hooked
347
-	# to do some action before.
348
-	#  -> Custom dist target?
349
-	#     add_custom_target(dist COMMAND ${CMAKE_MAKE_PROGRAM} package_source)
350
-	#  -> ${_html_output_dir} could contain online links by default,
351
-	#     then it could be copied to binary dir and rebased to relative
352
-	#       * Looks like a very good idea, can work even without gtk-doc
353
-	#  -> Or it can be first xreffed in the binary dir and then
354
-	#     converted to online links in ${_html_output_dir}
355
-	#       * Which one of those should be installed?
356
-	#         The one in the binary directory or should the
357
-	#         ${_html_output_dir} be rebased?
358
-	#       * A rebasing custom command may create the binary directory
359
-	#         if it doesn't exist
360
-	#
361
-	# When creating the source tarball for distribution,
362
-	# gtkdoc-rebase turns all external links into web-links.
363
-	# When installing distributed (pregenerated) docs the same
364
-	# application will try to turn links back to local links
365
-	# (where those docs are installed).
366
-
367
-	add_custom_target (${_target_name} ${_all}
368
-		DEPENDS ${_top_output})
369
-endfunction (GTK_DOC_RUN)
370
-
371
-

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

@@ -71,7 +71,7 @@ ld_category_view_default_init (LdCategoryViewInterface *iface)
71 71
 
72 72
 /**
73 73
  * ld_category_view_set_category:
74
- * @self: an #LdCategorylView object.
74
+ * @self: an #LdCategoryView object.
75 75
  * @category: the #LdCategory to be assigned to the view.
76 76
  *
77 77
  * Assign an #LdCategory object to the view.

Loading…
Cancel
Save