Add documentation generator and mock docs

author: Matthias Vogelgesang <matthias.vogelgesang@gmail.com> 2012-09-21 19:24:36 +0200
committer: Matthias Vogelgesang <matthias.vogelgesang@gmail.com> 2012-09-21 19:24:36 +0200
commit: e5ff011119ac42e48f3f3521b789a18bdfdfb51e (patch)
tree: f5d55718441301d2612db079b493ede7a4f79421
parent: f2c4098e756b237aa0654f71a0f437086d5e667e (diff)
download: libuca-e5ff011119ac42e48f3f3521b789a18bdfdfb51e.tar.gz
libuca-e5ff011119ac42e48f3f3521b789a18bdfdfb51e.tar.bz2
libuca-e5ff011119ac42e48f3f3521b789a18bdfdfb51e.tar.xz
libuca-e5ff011119ac42e48f3f3521b789a18bdfdfb51e.zip
6 files changed, 256 insertions, 0 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt
index ae371ff..bc65dc1 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -29,3 +29,4 @@ SET(UCA_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR})
 
 add_subdirectory(src)
 add_subdirectory(test)
+add_subdirectory(tools)
diff --git a/docs/manual.md b/docs/manual.md
index 5600d3f..cff6f18 100644
--- a/docs/manual.md
+++ b/docs/manual.md
@@ -245,6 +245,12 @@ The following cameras are supported:
 * Pylon
 * UFO Camera developed at KIT/IPE.
 
+## Property documentation
+
+* [mock][mock-doc]
+
+[mock-doc]: mock.html
+
 
 # More API
 
diff --git a/docs/mock.html b/docs/mock.html
new file mode 100644
index 0000000..0d38fc8
--- /dev/null
+++ b/docs/mock.html
@@ -0,0 +1,70 @@
+<html><head><link rel="stylesheet" href="style.css" type="text/css" /><link href='http://fonts.googleapis.com/css?family=Droid+Sans:400,700|Droid+Serif:400,400italic|Inconsolata' rel='stylesheet' type='text/css'><title>mock &mdash; properties</title></head><body><div id="header"><h1 class="title">Property documentation of mock</h1><h2>Properties</h2><ul id="toc"><li><code><a href=#name>"name"</a></code></li><li><code><a href=#sensor-width>"sensor-width"</a></code></li><li><code><a href=#sensor-height>"sensor-height"</a></code></li><li><code><a href=#sensor-bitdepth>"sensor-bitdepth"</a></code></li><li><code><a href=#sensor-horizontal-binning>"sensor-horizontal-binning"</a></code></li><li><code><a href=#sensor-horizontal-binnings>"sensor-horizontal-binnings"</a></code></li><li><code><a href=#sensor-vertical-binning>"sensor-vertical-binning"</a></code></li><li><code><a href=#sensor-vertical-binnings>"sensor-vertical-binnings"</a></code></li><li><code><a href=#sensor-max-frame-rate>"sensor-max-frame-rate"</a></code></li><li><code><a href=#trigger-mode>"trigger-mode"</a></code></li><li><code><a href=#exposure-time>"exposure-time"</a></code></li><li><code><a href=#roi-x0>"roi-x0"</a></code></li><li><code><a href=#roi-y0>"roi-y0"</a></code></li><li><code><a href=#roi-width>"roi-width"</a></code></li><li><code><a href=#roi-height>"roi-height"</a></code></li><li><code><a href=#roi-width-multiplier>"roi-width-multiplier"</a></code></li><li><code><a href=#roi-height-multiplier>"roi-height-multiplier"</a></code></li><li><code><a href=#has-streaming>"has-streaming"</a></code></li><li><code><a href=#has-camram-recording>"has-camram-recording"</a></code></li><li><code><a href=#transfer-asynchronously>"transfer-asynchronously"</a></code></li><li><code><a href=#is-recording>"is-recording"</a></code></li><li><code><a href=#is-readout>"is-readout"</a></code></li><li><code><a href=#frame-rate>"frame-rate"</a></code></li></ul><h2>Details</h2><dl><dt id="name"><a href="#toc">name</a></dt>
+<dd><pre><code class="prop-type">"name" : gchararray : Read-only</code></pre>
+<p>Name of the camera</p>
+</dd><dt id="sensor-width"><a href="#toc">sensor-width</a></dt>
+<dd><pre><code class="prop-type">"sensor-width" : guint : Read-only</code></pre>
+<p>Width of the sensor in pixels</p>
+</dd><dt id="sensor-height"><a href="#toc">sensor-height</a></dt>
+<dd><pre><code class="prop-type">"sensor-height" : guint : Read-only</code></pre>
+<p>Height of the sensor in pixels</p>
+</dd><dt id="sensor-bitdepth"><a href="#toc">sensor-bitdepth</a></dt>
+<dd><pre><code class="prop-type">"sensor-bitdepth" : guint : Read-only</code></pre>
+<p>Number of bits per pixel</p>
+</dd><dt id="sensor-horizontal-binning"><a href="#toc">sensor-horizontal-binning</a></dt>
+<dd><pre><code class="prop-type">"sensor-horizontal-binning" : guint : Read / Write</code></pre>
+<p>Number of sensor ADCs that are combined to one pixel in horizontal direction</p>
+</dd><dt id="sensor-horizontal-binnings"><a href="#toc">sensor-horizontal-binnings</a></dt>
+<dd><pre><code class="prop-type">"sensor-horizontal-binnings" : GValueArray : Read-only</code></pre>
+<p>Array of possible binnings in horizontal direction</p>
+</dd><dt id="sensor-vertical-binning"><a href="#toc">sensor-vertical-binning</a></dt>
+<dd><pre><code class="prop-type">"sensor-vertical-binning" : guint : Read / Write</code></pre>
+<p>Number of sensor ADCs that are combined to one pixel in vertical direction</p>
+</dd><dt id="sensor-vertical-binnings"><a href="#toc">sensor-vertical-binnings</a></dt>
+<dd><pre><code class="prop-type">"sensor-vertical-binnings" : GValueArray : Read-only</code></pre>
+<p>Array of possible binnings in vertical direction</p>
+</dd><dt id="sensor-max-frame-rate"><a href="#toc">sensor-max-frame-rate</a></dt>
+<dd><pre><code class="prop-type">"sensor-max-frame-rate" : gfloat : Read-only</code></pre>
+<p>Maximum frame rate at full frame resolution</p>
+</dd><dt id="trigger-mode"><a href="#toc">trigger-mode</a></dt>
+<dd><pre><code class="prop-type">"trigger-mode" : UcaCameraTrigger : Read / Write</code></pre>
+<p>Trigger mode</p>
+</dd><dt id="exposure-time"><a href="#toc">exposure-time</a></dt>
+<dd><pre><code class="prop-type">"exposure-time" : gdouble : Read / Write</code></pre>
+<p>Exposure time in seconds</p>
+</dd><dt id="roi-x0"><a href="#toc">roi-x0</a></dt>
+<dd><pre><code class="prop-type">"roi-x0" : guint : Read / Write</code></pre>
+<p>Horizontal coordinate</p>
+</dd><dt id="roi-y0"><a href="#toc">roi-y0</a></dt>
+<dd><pre><code class="prop-type">"roi-y0" : guint : Read / Write</code></pre>
+<p>Vertical coordinate</p>
+</dd><dt id="roi-width"><a href="#toc">roi-width</a></dt>
+<dd><pre><code class="prop-type">"roi-width" : guint : Read / Write</code></pre>
+<p>Width of the region of interest</p>
+</dd><dt id="roi-height"><a href="#toc">roi-height</a></dt>
+<dd><pre><code class="prop-type">"roi-height" : guint : Read / Write</code></pre>
+<p>Height of the region of interest</p>
+</dd><dt id="roi-width-multiplier"><a href="#toc">roi-width-multiplier</a></dt>
+<dd><pre><code class="prop-type">"roi-width-multiplier" : guint : Read-only</code></pre>
+<p>Minimum possible step size of horizontal ROI</p>
+</dd><dt id="roi-height-multiplier"><a href="#toc">roi-height-multiplier</a></dt>
+<dd><pre><code class="prop-type">"roi-height-multiplier" : guint : Read-only</code></pre>
+<p>Minimum possible step size of vertical ROI</p>
+</dd><dt id="has-streaming"><a href="#toc">has-streaming</a></dt>
+<dd><pre><code class="prop-type">"has-streaming" : gboolean : Read-only</code></pre>
+<p>Is the camera able to stream the data</p>
+</dd><dt id="has-camram-recording"><a href="#toc">has-camram-recording</a></dt>
+<dd><pre><code class="prop-type">"has-camram-recording" : gboolean : Read-only</code></pre>
+<p>Is the camera able to record the data in-camera</p>
+</dd><dt id="transfer-asynchronously"><a href="#toc">transfer-asynchronously</a></dt>
+<dd><pre><code class="prop-type">"transfer-asynchronously" : gboolean : Read / Write</code></pre>
+<p>Specify whether data should be transfered asynchronously using a specified callback</p>
+</dd><dt id="is-recording"><a href="#toc">is-recording</a></dt>
+<dd><pre><code class="prop-type">"is-recording" : gboolean : Read-only</code></pre>
+<p>Is the camera currently recording</p>
+</dd><dt id="is-readout"><a href="#toc">is-readout</a></dt>
+<dd><pre><code class="prop-type">"is-readout" : gboolean : Read-only</code></pre>
+<p>Is camera in readout mode</p>
+</dd><dt id="frame-rate"><a href="#toc">frame-rate</a></dt>
+<dd><pre><code class="prop-type">"frame-rate" : gfloat : Read / Write</code></pre>
+<p>Number of frames per second that are taken</p>
+</dd></dl></body></html>
diff --git a/docs/style.css b/docs/style.css
index 646a097..beccf45 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -126,6 +126,10 @@ ul, ol {
     margin-bottom: 24px;
 }
 
+ul#toc {
+    list-style-type: none;
+}
+
 li + li {
     margin-top: 0.1em;
 }
diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt
new file mode 100644
index 0000000..957fdbf
--- /dev/null
+++ b/tools/CMakeLists.txt
@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 2.8)
+
+add_definitions("--std=c99 -Wall")
+
+# --- Find packages and libraries ---------------------------------------------
+find_package(PkgConfig)
+
+pkg_check_modules(GLIB2 glib-2.0>=2.24 REQUIRED)
+pkg_check_modules(GOBJECT2 gobject-2.0>=2.24 REQUIRED)
+
+# --- Build targets -----------------------------------------------------------
+include_directories(
+    ${GLIB2_INCLUDE_DIRS}
+    ${GOBJECT2_INCLUDE_DIRS}
+    ${CMAKE_CURRENT_BINARY_DIR}/../src/
+    ${CMAKE_CURRENT_SOURCE_DIR}/../src
+    )
+
+add_executable(gen-doc gen-doc.c)
+
+target_link_libraries(gen-doc uca 
+    ${GLIB2_LIBRARIES}
+    ${GOBJECT2_LIBRARIES}
+    )
diff --git a/tools/gen-doc.c b/tools/gen-doc.c
new file mode 100644
index 0000000..d9b6b41
--- /dev/null
+++ b/tools/gen-doc.c
@@ -0,0 +1,151 @@
+/* Copyright (C) 2012 Matthias Vogelgesang <matthias.vogelgesang@kit.edu>
+   (Karlsruhe Institute of Technology)
+
+   This library is free software; you can redistribute it and/or modify it
+   under the terms of the GNU Lesser General Public License as published by the
+   Free Software Foundation; either version 2.1 of the License, or (at your
+   option) any later version.
+
+   This library is distributed in the hope that it will be useful, but WITHOUT
+   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+   FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+   details.
+
+   You should have received a copy of the GNU Lesser General Public License along
+   with this library; if not, write to the Free Software Foundation, Inc., 51
+   Franklin St, Fifth Floor, Boston, MA 02110, USA */
+
+#include <glib-object.h>
+#include "uca-plugin-manager.h"
+#include "uca-camera.h"
+
+
+static void
+print_usage (void)
+{
+    GList *types;
+    UcaPluginManager *manager;
+
+    manager = uca_plugin_manager_new ();
+    g_print ("Usage: gen-doc [ ");
+    types = uca_plugin_manager_get_available_cameras (manager);
+
+    if (types == NULL) {
+        g_print ("] -- no camera plugin found\n");
+        return;
+    }
+
+    for (GList *it = g_list_first (types); it != NULL; it = g_list_next (it)) {
+        gchar *name = (gchar *) it->data;
+        if (g_list_next (it) == NULL)
+            g_print ("%s ]\n", name);
+        else
+            g_print ("%s, ", name);
+    }
+}
+
+static const gchar *
+get_flags_description (GParamSpec *pspec)
+{
+    static const gchar *descriptions[] = {
+        "",
+        "Read-only",
+        "Write-only",
+        "Read / Write",
+        ""
+    };
+
+    if (pspec->flags >= 3)
+        return descriptions[3];
+
+    return descriptions[pspec->flags];
+}
+
+static void
+print_property_toc (GParamSpec **pspecs, guint n_props)
+{
+    g_print ("<h2>Properties</h2><ul id=\"toc\">");
+
+    for (guint i = 0; i < n_props; i++) {
+        GParamSpec *pspec = pspecs[i]; 
+        const gchar *name = g_param_spec_get_name (pspec);
+    
+        g_print ("<li><code><a href=#%s>\"%s\"</a></code></li>", name, name);
+    }
+
+    g_print ("</ul>");
+}
+
+static void
+print_property_descriptions (GParamSpec **pspecs, guint n_props)
+{
+    g_print ("<h2>Details</h2><dl>");
+
+    for (guint i = 0; i < n_props; i++) {
+        GParamSpec *pspec = pspecs[i]; 
+        const gchar *name = g_param_spec_get_name (pspec);
+
+        g_print ("<dt id=\"%s\"><a href=\"#toc\">%s</a></dt>\n", name, name);
+        g_print ("<dd>");
+        g_print ("<pre><code class=\"prop-type\">\"%s\" : %s : %s</code></pre>\n", 
+                 name, 
+                 g_type_name (pspec->value_type),
+                 get_flags_description (pspec));
+        g_print ("<p>%s</p>\n", g_param_spec_get_blurb (pspec));
+        g_print ("</dd>");
+    }
+
+    g_print ("</dl>");
+}
+
+static void
+print_properties (UcaCamera *camera)
+{
+    GObjectClass *oclass;
+    GParamSpec **pspecs;
+    guint n_props;
+    
+    oclass = G_OBJECT_GET_CLASS (camera);
+    pspecs = g_object_class_list_properties (oclass, &n_props);
+
+    print_property_toc (pspecs, n_props);
+    print_property_descriptions (pspecs, n_props);
+
+    g_free (pspecs);
+}
+
+static const gchar *html_header = "<html><head>\
+<link rel=\"stylesheet\" href=\"style.css\" type=\"text/css\" />\
+<link href='http://fonts.googleapis.com/css?family=Droid+Sans:400,700|Droid+Serif:400,400italic|Inconsolata' rel='stylesheet' type='text/css'>\
+<title>%s &mdash; properties</title></head><body>";
+static const gchar *html_footer = "</body></html>";
+
+int main(int argc, char *argv[])
+{
+    UcaPluginManager *manager;
+    UcaCamera *camera;
+    GError *error = NULL;
+
+    g_type_init();
+
+    if (argc < 2) {
+        print_usage();
+        return 1;
+    }
+
+    manager = uca_plugin_manager_new ();
+    camera = uca_plugin_manager_new_camera (manager, argv[1], &error);
+
+    if (camera == NULL) {
+        g_print("Error during initialization: %s\n", error->message);
+        return 1;
+    }
+
+    g_print (html_header, argv[1]);
+    g_print ("<div id=\"header\"><h1 class=\"title\">Property documentation of %s</h1>", argv[1]);
+    print_properties (camera);
+    g_print ("%s\n", html_footer);
+
+    g_object_unref (camera);
+    g_object_unref (manager);
+}
author	Matthias Vogelgesang <matthias.vogelgesang@gmail.com>	2012-09-21 19:24:36 +0200
committer	Matthias Vogelgesang <matthias.vogelgesang@gmail.com>	2012-09-21 19:24:36 +0200
commit	e5ff011119ac42e48f3f3521b789a18bdfdfb51e (patch)
tree	f5d55718441301d2612db079b493ede7a4f79421
parent	f2c4098e756b237aa0654f71a0f437086d5e667e (diff)
download	libuca-e5ff011119ac42e48f3f3521b789a18bdfdfb51e.tar.gz libuca-e5ff011119ac42e48f3f3521b789a18bdfdfb51e.tar.bz2 libuca-e5ff011119ac42e48f3f3521b789a18bdfdfb51e.tar.xz libuca-e5ff011119ac42e48f3f3521b789a18bdfdfb51e.zip