doc: add gtk-doc to generate documentation

Current limitation is horrible no support to sections: we have to to
have separate header files or to maintain the libkmod-sections.txt file.
We are doing the latter.

diff --git a/Makefile.am b/Makefile.am
index 913535962104c391be9fbfa44ef8749434d6ce85..8bbe0256a97bc31c589fb1b2058fc91241d67c2b 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,3 +1,5 @@
+SUBDIRS = . libkmod/docs
+
 EXTRA_DIST =
 CLEANFILES =
 ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
@@ -144,3 +146,5 @@ test_test_blacklist_LDADD = libkmod/libkmod.la
 test_test_elf_LDADD = libkmod/libkmod.la
 test_test_probe_LDADD = libkmod/libkmod.la
 test_test_invalidate_config_LDADD = libkmod/libkmod.la
+
+DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc

diff --git a/autogen.sh b/autogen.sh
index 6ba92d8d78a98b6b9818ef4b955039a214676b64..aa59f3b64f99a4af5f4a80a0dc114bf8c142ddf8 100755 (executable)
--- a/autogen.sh
+++ b/autogen.sh
@@ -1,5 +1,6 @@
 #!/bin/sh -e
 
+gtkdocize --docdir libkmod/docs
 autoreconf --install --symlink
 
 MYCFLAGS="-g -O2 -Werror"

diff --git a/configure.ac b/configure.ac
index 7ba29be9b05ea9e5a93b74cc6d974571f0e29068..bbb4d1f43b0c65826ea7882abe073cee5754978d 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -128,8 +128,12 @@ CC_CHECK_CFLAGS_APPEND([ \
 AC_CONFIG_HEADERS(config.h)
 AC_CONFIG_FILES([
        Makefile
+       libkmod/docs/Makefile
+       libkmod/docs/version.xml
 ])
 
+GTK_DOC_CHECK([1.14],[--flavour no-tmpl-flat])
+
 AC_OUTPUT
 AC_MSG_RESULT([
        $PACKAGE $VERSION
@@ -151,4 +155,5 @@ AC_MSG_RESULT([
        logging:                ${enable_logging}
        compression:            xz=${with_xz}  zlib=${with_zlib}
        debug:                  ${enable_debug}
+       doc:                    ${enable_gtk_doc}
 ])

diff --git a/libkmod/docs/.gitignore b/libkmod/docs/.gitignore
new file mode 100644 (file)
index 0000000..21e2279
--- /dev/null
+++ b/libkmod/docs/.gitignore
@@ -0,0 +1,12 @@
+*.bak
+*.stamp
+*.sgml
+libkmod.*
+libkmod-*.xml
+!libkmod-docs.xml
+libkmod-*.txt
+!libkmod-sections.txt
+version.xml
+xml
+html
+gtk-doc.make

diff --git a/libkmod/docs/Makefile.am b/libkmod/docs/Makefile.am
new file mode 100644 (file)
index 0000000..8b37d58
--- /dev/null
+++ b/libkmod/docs/Makefile.am
@@ -0,0 +1,41 @@
+
+AUTOMAKE_OPTIONS = 1.11
+
+DOC_MODULE = libkmod
+
+DOC_MODULE_VERSION = 3
+
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml
+
+DOC_SOURCE_DIR = ../
+
+SCAN_OPTIONS = --ignore-decorators="__must_check|KMOD_EXPORT"
+
+MKDB_OPTIONS = --xml-mode --output-format=xml --name-space kmod --tmpl-dir=.
+
+MKTMPL_OPTIONS = --output-dir=.
+
+MKHTML_OPTIONS = --path=$(abs_srcdir)/doc --path=$(abs_builddir)/doc
+
+HFILE_GLOB = $(top_srcdir)/libkmod/libkmod.h
+CFILE_GLOB = $(top_srcdir)/libkmod/libkmod.c $(top_srcdir)/libkmod/libkmod-module.c $(top_srcdir)/libkmod/libkmod-list.c
+
+IGNORE_HFILES = macro.h \
+               libkmod-private.h \
+               libkmod-util.h \
+               libkmod-array.h \
+               libkmod-hash.h \
+               libkmod-index.h
+
+content_files = version.xml
+
+if ENABLE_GTK_DOC
+include $(top_srcdir)/libkmod/docs/gtk-doc.make
+else
+EXTRA_DIST = libkmod-docs.xml libkmod-sections.txt
+endif
+
+DISTCLEANFILES = $(DOC_MODULE)-docs.xml \
+                       $(DOC_MODULE).types $(DOC_MODULE)-*.txt *.sgml *.bak
+
+MAINTAINERCLEANFILES = Makefile.in gtk-doc.make

diff --git a/libkmod/docs/libkmod-docs.xml b/libkmod/docs/libkmod-docs.xml
new file mode 100644 (file)
index 0000000..20f07c5
--- /dev/null
+++ b/libkmod/docs/libkmod-docs.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
+  <bookinfo>
+    <title>libkmod Reference Manual</title>
+    <releaseinfo>for libkmod version &version;</releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>libkmod</title>
+    <xi:include href="xml/libkmod.xml"/>
+    <xi:include href="xml/libkmod-list.xml"/>
+    <xi:include href="xml/libkmod-module.xml"/>
+    <xi:include href="xml/libkmod-loaded.xml"/>
+
+  </chapter>
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+     <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>

diff --git a/libkmod/docs/libkmod-sections.txt b/libkmod/docs/libkmod-sections.txt
new file mode 100644 (file)
index 0000000..246b1ba
--- /dev/null
+++ b/libkmod/docs/libkmod-sections.txt
@@ -0,0 +1,86 @@
+<SECTION>
+<FILE>libkmod</FILE>
+kmod_ctx
+kmod_new
+kmod_ref
+kmod_unref
+
+kmod_load_resources
+kmod_unload_resources
+kmod_validate_resources
+
+kmod_set_log_priority
+kmod_get_log_priority
+kmod_set_log_fn
+kmod_get_userdata
+kmod_set_userdata
+</SECTION>
+
+<SECTION>
+<FILE>libkmod-list</FILE>
+kmod_list
+kmod_list_foreach
+kmod_list_foreach_reverse
+kmod_list_last
+kmod_list_next
+kmod_list_prev
+</SECTION>
+
+<SECTION>
+<FILE>libkmod-module</FILE>
+kmod_module
+kmod_module_new_from_loaded
+kmod_module_new_from_lookup
+kmod_module_new_from_name
+kmod_module_new_from_path
+
+kmod_module_ref
+kmod_module_unref
+kmod_module_unref_list
+
+kmod_module_insert_module
+kmod_module_probe_insert_module
+kmod_module_remove_module
+
+kmod_module_get_module
+kmod_module_get_dependencies
+kmod_module_get_softdeps
+kmod_module_get_filtered_blacklist
+kmod_module_get_install_commands
+kmod_module_get_remove_commands
+kmod_module_get_name
+kmod_module_get_options
+kmod_module_get_path
+
+kmod_module_get_initstate
+kmod_module_initstate_str
+kmod_module_get_size
+kmod_module_get_refcnt
+kmod_module_get_holders
+
+kmod_module_get_dependency_symbols
+kmod_module_dependency_symbol_get_bind
+kmod_module_dependency_symbol_get_crc
+kmod_module_dependency_symbol_get_symbol
+kmod_module_dependency_symbols_free_list
+
+kmod_module_get_sections
+kmod_module_section_free_list
+kmod_module_section_get_address
+kmod_module_section_get_name
+
+kmod_module_get_symbols
+kmod_module_symbol_get_crc
+kmod_module_symbol_get_symbol
+kmod_module_symbols_free_list
+
+kmod_module_get_versions
+kmod_module_version_get_crc
+kmod_module_version_get_symbol
+kmod_module_versions_free_list
+
+kmod_module_get_info
+kmod_module_info_free_list
+kmod_module_info_get_key
+kmod_module_info_get_value
+</SECTION>

diff --git a/libkmod/docs/version.xml.in b/libkmod/docs/version.xml.in
new file mode 100644 (file)
index 0000000..d78bda9
--- /dev/null
+++ b/libkmod/docs/version.xml.in
@@ -0,0 +1 @@
+@VERSION@

diff --git a/m4/.gitignore b/m4/.gitignore
index 8bab51c22bf555d70c25e02a2389f369c657847e..d59889ae09e0df67b23912c262cc2f23c742857e 100644 (file)
--- a/m4/.gitignore
+++ b/m4/.gitignore
@@ -3,4 +3,4 @@ ltoptions.m4
 ltsugar.m4
 ltversion.m4
 lt~obsolete.m4
-
+gtk-doc.m4