doc: Add auto-generated Wayland Library chapter

For now only Wayland Client API is described on that chapter, which is
extracted via doxygen on ./src/wayland-client.h. We apply a stylesheet
(doxygen-to-publican) on doxygen output so it becomes docbook valid.

Now all we need to do is populate that header while developing in order to
grow a decent documentation. So please use it!

Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>

configure.ac

@@ -78,6 +78,11 @@ AM_CONDITIONAL([HAVE_XSLTPROC], [test "x$XSLTPROC" != "x"])
 
 if test "x$enable_documentation" = "xyes"; then
 	AC_PATH_PROG(PUBLICAN, publican)
+
+	AC_CONFIG_FILES([
+	doc/doxygen/wayland.doxygen
+	])
+
 fi
 AM_CONDITIONAL([HAVE_PUBLICAN], [test "x$PUBLICAN" != "x"])
 
@@ -88,6 +93,7 @@ AC_CONFIG_FILES([Makefile
 		 cursor/wayland-cursor-uninstalled.pc
 		 doc/Makefile
 		 doc/Wayland/Makefile
+		 doc/doxygen/Makefile
 		 doc/man/Makefile
 		 src/Makefile
 		 src/wayland-server-uninstalled.pc

doc/Makefile.am

@@ -1 +1 @@
-SUBDIRS = Wayland man
+SUBDIRS = doxygen Wayland man

doc/Wayland/Makefile.am

@@ -5,6 +5,7 @@ publican_sources = \
 	$(srcdir)/en_US/Book_Info.xml \
 	$(srcdir)/en_US/Wayland.xml \
 	$(srcdir)/en_US/Protocol.xml \
+	$(srcdir)/en_US/Library.xml \
 	$(srcdir)/en_US/Compositors.xml \
 	$(srcdir)/en_US/Overview.xml \
 	$(srcdir)/en_US/images/icon.svg  \
@@ -17,7 +18,8 @@ noinst_DATA = Wayland $(publican_targets)
 pubdir = $(docdir)/Wayland/en-US
 
 publican_targets = $(publican_sources:$(srcdir)/en_US%=$(builddir)/en-US%) \
-	en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml
+	en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml \
+	en-US/WaylandClientAPI.xml
 
 # The Protocol.xml is purely generated and required before running publican
 en-US/ProtocolSpec.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-to-docbook.xsl
@@ -30,11 +32,15 @@ en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/proto
 	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol-interfaces-to-docbook.xsl \
 		$(top_srcdir)/protocol/wayland.xml > en-US/ProtocolInterfaces.xml
 
+en-US/WaylandClientAPI.xml: $(top_srcdir)/doc/doxygen/xml/wayland-client_8h.xml $(srcdir)/doxygen-to-publican.xsl
+	$(AM_V_GEN)$(MKDIR_P) en-US/images
+	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/doxygen-to-publican.xsl \
+		$(top_srcdir)/doc/doxygen/xml/wayland-client_8h.xml > en-US/WaylandClientAPI.xml
 
 # Copy the en_US source files into en-US destination
 # This is required for out-of-source-tree build as publican does not allow us
 # to specify the location of the source code.
-$(builddir)/en-US/%: $(srcdir)/en_US/% en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml $(publican_sources)
+$(builddir)/en-US/%: $(srcdir)/en_US/% en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(publican_sources)
 	$(AM_V_GEN)cp -f $< $@
 
 # Run publican for the builddir on the generated (or copied) source
@@ -49,7 +55,7 @@ Wayland: $(publican_targets)
 		--config $(srcdir)/publican.cfg
 	@touch Wayland
 
-CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml $(publican_targets)
+CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(publican_targets)
 
 clean-local:
 	$(AM_V_at)rm -fr en-US
@@ -79,4 +85,4 @@ uninstall-local:
 
 endif
 
-EXTRA_DIST = $(publican_sources) publican.cfg protocol-to-docbook.xsl
+EXTRA_DIST = $(publican_sources) publican.cfg protocol-to-docbook.xsl protocol-interfaces-to-docbook.xsl doxygen-to-publican.xsl

doc/Wayland/doxygen-to-publican.xsl

@@ -0,0 +1,46 @@
+<?xml version="1.0" ?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:output method="xml" encoding="UTF-8" indent="yes" />
+
+<xsl:template match="/">
+  <!-- insert docbook's DOCTYPE blurb -->
+    <xsl:text disable-output-escaping = "yes"><![CDATA[
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+  <!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
+%BOOK_ENTITIES;
+]>
+]]></xsl:text>
+
+  <section id="sect-Library-Client">
+    <title>Client API</title>
+    <para>Following is the Wayland library interface for clients
+	  (<emphasis>libwayland-client</emphasis>). Note that most of the
+	  procedures are related with IPC, which is the main responsibility of
+	  the library.
+    </para>
+
+    <para>
+    <variablelist>
+    <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" />
+    </variablelist>
+    </para>
+  </section>
+</xsl:template>
+
+<xsl:template match="memberdef" >
+    <xsl:if test="@kind = 'function'">
+  <varlistentry>
+
+      <term>
+      <xsl:value-of select="name" />
+      </term>
+    <listitem>
+    <para>
+      <xsl:value-of select="briefdescription" />
+    </para>
+    </listitem>
+  </varlistentry>
+  </xsl:if>
+</xsl:template>
+
+</xsl:stylesheet>

doc/Wayland/en_US/Library.xml

@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-Library">
+  <title>Wayland Library</title>
+  <xi:include href="WaylandClientAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</chapter>

doc/Wayland/en_US/Wayland.xml

@@ -8,6 +8,7 @@
   <xi:include href="Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Protocol.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="Library.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Compositors.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="ProtocolSpec.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 </book>

doc/doxygen/Makefile.am

@@ -0,0 +1,9 @@
+
+noinst_DATA = xml/index.xml
+dist_noinst_DATA = wayland.doxygen.in
+
+xml/index.xml:
+	doxygen wayland.doxygen
+
+clean-local:
+	rm -rf xml/