Generate documentation with gtk-doc

4 files changed, 112 insertions, 5 deletions

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index db2ba46..759d5b7 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -41,8 +41,8 @@ if (PF_FOUND)
     option(HAVE_PHOTON_FOCUS "Camera: Photon Focus MV2-D1280-640-CL-8" ON)
 
     if (HAVE_PHOTON_FOCUS)
-        set(uca_SRCS ${uca_SRCS} cameras/uca-pf-camera.c)
-        set(uca_HDRS ${uca_HDRS} cameras/uca-pf-camera.h)
+        #set(uca_SRCS ${uca_SRCS} cameras/uca-pf-camera.c)
+        #set(uca_HDRS ${uca_HDRS} cameras/uca-pf-camera.h)
         set(uca_LIBS ${uca_LIBS} ${PF_LIBRARIES})
 
         include_directories(${PF_INCLUDE_DIRS})
@@ -110,6 +110,81 @@ target_link_libraries(uca-gobject
     ${uca_LIBS})
 
 
+# --- Build documentation -----------------------------------------------------
+pkg_check_modules(GTK_DOC gtk-doc)
+if(GTK_DOC_FOUND)
+    option(WITH_GTK_DOC "Build documentation" ON)
+    if (WITH_GTK_DOC)
+        set(docs_dir "${CMAKE_CURRENT_BINARY_DIR}/..")
+        set(docs_out "${docs_dir}/reference")
+        file(MAKE_DIRECTORY ${docs_out})
+
+        configure_file(${CMAKE_CURRENT_SOURCE_DIR}/uca-docs.xml.in
+            ${docs_out}/uca-docs.xml)
+
+        set(reference_files 
+            "${docs_out}/index.html"
+            "${docs_out}/api-index-full.html"
+            "${docs_out}/ch01.html"
+            "${docs_out}/UcaCamera.html"
+            "${docs_out}/UcaMockCamera.html"
+            "${docs_out}/UcaPcoCamera.html"
+            "${docs_out}/UcaUfoCamera.html"
+            "${docs_out}/style.css"
+            "${docs_out}/uca.devhelp2"
+            "${docs_out}/home.png"
+            "${docs_out}/left.png"
+            "${docs_out}/right.png"
+            "${docs_out}/up.png")
+
+        find_program(GTK_DOC_SCAN gtkdoc-scan REQUIRED)
+        find_program(GTK_DOC_SCANGOBJ gtkdoc-scangobj REQUIRED)
+        find_program(GTK_DOC_MKDB gtkdoc-mkdb REQUIRED)
+        find_program(GTK_DOC_MKHTML gtkdoc-mkhtml REQUIRED)
+
+        get_directory_property(_current_include_dirs INCLUDE_DIRECTORIES)
+
+        set(GTK_DOC_CFLAGS)
+        foreach(_incl ${_current_include_dirs})
+            set(GTK_DOC_CFLAGS "-I${_incl} ${GTK_DOC_CFLAGS}")
+        endforeach()
+
+        configure_file("${CMAKE_CURRENT_SOURCE_DIR}/scangobj.sh.in" "${docs_out}/scangobj.sh")
+
+        add_custom_command(OUTPUT ${docs_out}/uca-decl.txt
+            COMMAND ${GTK_DOC_SCAN}
+                    --module=uca
+                    --source-dir=${CMAKE_CURRENT_SOURCE_DIR}
+                    DEPENDS ${uca_SRCS} 
+            WORKING_DIRECTORY ${docs_out})
+
+        add_custom_command(OUTPUT ${docs_out}/uca.args
+            COMMAND sh scangobj.sh
+            DEPENDS uca-gobject ${docs_out}/uca-decl.txt
+            WORKING_DIRECTORY ${docs_out})
+
+        add_custom_command(OUTPUT ${docs_out}/sgml.stamp
+            COMMAND ${GTK_DOC_MKDB}
+                    --module=uca
+                    --source-dir=${CMAKE_CURRENT_SOURCE_DIR}
+                    --output-format=xml
+                    DEPENDS ${docs_out}/uca-decl.txt ${docs_out}/uca.args
+            WORKING_DIRECTORY ${docs_out})
+
+        add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/../html.stamp
+            COMMAND ${GTK_DOC_MKHTML}
+                    uca
+                    ${docs_out}/uca-docs.xml
+            DEPENDS ${docs_out}/sgml.stamp
+            WORKING_DIRECTORY ${docs_out})
+
+        add_custom_target(reference ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/../html.stamp)
+
+        install(FILES ${reference_files} DESTINATION share/gtk-doc/html/uca)
+    endif()
+endif(GTK_DOC_FOUND)
+
+
 # --- Install target ----------------------------------------------------------
 set(LIB_INSTALL_DIR "lib${LIB_SUFFIX}")
 
diff --git a/src/scangobj.sh.in b/src/scangobj.sh.in
new file mode 100644
index 0000000..9b444ae
--- /dev/null
+++ b/src/scangobj.sh.in
@@ -0,0 +1 @@
+LD_LIBRARY_PATH=${CMAKE_CURRENT_BINARY_DIR} CC=gcc CFLAGS="${GTK_DOC_CFLAGS}" LDFLAGS="${GTK_DOC_LDFLAGS} -L${CMAKE_CURRENT_BINARY_DIR} -L${CMAKE_CURRENT_BINARY_DIR} -luca-gobject `pkg-config --libs gtk+-2.0`" gtkdoc-scangobj --module=uca
diff --git a/src/uca-camera.c b/src/uca-camera.c
index 5a30689..bcfe828 100644
--- a/src/uca-camera.c
+++ b/src/uca-camera.c
@@ -326,11 +326,11 @@ gchar **uca_camera_get_types()
 
 /**
  * uca_camera_new:
- * @param type: Type name of the camera
+ * @type: Type name of the camera
  * @error: Location to store an error or %NULL
  *
  * Factory method for instantiating cameras by names listed in
- * uca_camera_get_type().
+ * uca_camera_get_types().
  *
  * Returns: A new #UcaCamera of the correct type or %NULL if type was not found
  */
@@ -481,7 +481,8 @@ void uca_camera_start_readout(UcaCamera *camera, GError **error)
 /**
  * uca_camera_set_grab_func:
  * @camera: A #UcaCamera object
- * func: A #UcaCameraGrabFunc callback function
+ * @func: A #UcaCameraGrabFunc callback function
+ * @user_data: Data that is passed on to #func
  *
  * Set the grab function that is called whenever a frame is readily transfered.
  */
diff --git a/src/uca-docs.xml.in b/src/uca-docs.xml.in
new file mode 100644
index 0000000..915e14c
--- /dev/null
+++ b/src/uca-docs.xml.in
@@ -0,0 +1,30 @@
+<?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>libuca Reference Manual</title>
+    <releaseinfo>
+        for libuca ${UCA_VERSION_STRING}. The latest version of this documentation can be found on-line at
+      <ulink role="online-location"
+          url="http://ufo.kit.edu/extra/libuca">http://ufo.kit.edu/extra/libuca</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>Unified Camera Access</title>
+        <xi:include href="xml/uca-camera.xml"/>
+    <xi:include href="xml/uca-mock-camera.xml"/>
+    <xi:include href="xml/uca-ufo-camera.xml"/>
+    <xi:include href="xml/uca-pco-camera.xml"/>
+
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+
+</book>