GNOME.org
 

[gupnp-dlna/wip/new-api: 6/15] Split documentation generation into two parts

commit 75201e3d3fab5198d41b158af91f95948d71626b
Author: Krzesimir Nowak <krnowak openismus com>
Date:   Thu Nov 15 15:28:02 2012 +0100

    Split documentation generation into two parts
    
    One part is for general users of GUPnP-DLNA API - i.e. about
    GUPnPDLNAProfile and GUPnPDLNAProfileGuesser. The other part is a semi
    public API for metadata extractor plugin writers.

 doc/gupnp-dlna-metadata/Makefile.am                |   88 +++++++++++++++++++
 .../gupnp-dlna-metadata-docs.sgml}                 |   35 +++-----
 doc/gupnp-dlna-sections.txt                        |   75 ----------------
 doc/gupnp-dlna.types                               |    3 -
 doc/gupnp-dlna/Makefile.am                         |   92 ++++++++++++++++++++
 doc/{ => gupnp-dlna}/dlna-profiles-example.xml     |    0
 doc/{ => gupnp-dlna}/gupnp-dlna-docs.sgml          |   15 ++--
 7 files changed, 201 insertions(+), 107 deletions(-)
---
diff --git a/doc/gupnp-dlna-metadata/Makefile.am b/doc/gupnp-dlna-metadata/Makefile.am
new file mode 100644
index 0000000..fbbb7f3
--- /dev/null
+++ b/doc/gupnp-dlna-metadata/Makefile.am
@@ -0,0 +1,88 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=gupnp-dlna-metadata
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=../../libgupnp-dlna/metadata
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=--deprecated-guards="GUPNP_DISABLE_DEPRECATED"
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS = \
+	--sgml-mode \
+	--output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS = \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gobject \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gmodule \
+	--extra-dir=../gupnp-dlna/html
+
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB = \
+	$(top_srcdir)/libgupnp-dlna/*.h \
+	$(top_srcdir)/libgupnp-dlna/metadata/*.h
+CFILE_GLOB = \
+	$(top_srcdir)/libgupnp-dlna/*.c \
+	$(top_srcdir)/libgupnp-dlna/metadata/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES =
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=../version.xml
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+INCLUDES=-I$(top_srcdir)
+GTKDOC_LIBS=$(top_builddir)/libgupnp-dlna/libgupnp-dlna-2.0.la
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
diff --git a/doc/gupnp-dlna-docs.sgml b/doc/gupnp-dlna-metadata/gupnp-dlna-metadata-docs.sgml
similarity index 66%
copy from doc/gupnp-dlna-docs.sgml
copy to doc/gupnp-dlna-metadata/gupnp-dlna-metadata-docs.sgml
index 8465da4..e4daf35 100644
--- a/doc/gupnp-dlna-docs.sgml
+++ b/doc/gupnp-dlna-metadata/gupnp-dlna-metadata-docs.sgml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
-<!ENTITY version SYSTEM "version.xml">
+<!ENTITY version SYSTEM "../version.xml">
 ]>
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
   <bookinfo>
@@ -10,16 +10,8 @@
     <releaseinfo>Version &version;</releaseinfo>
 
     <copyright>
-      <year>2010</year>
-      <holder>Arun Raghavan &lt;arun raghavan collabora co uk&gt;</holder>
-    </copyright>
-    <copyright>
-      <year>2010</year>
-      <holder>Collabora Multimedia</holder>
-    </copyright>
-    <copyright>
-      <year>2010</year>
-      <holder>Nokia Corporation</holder>
+      <year>2012</year>
+      <holder>Intel Corporation</holder>
     </copyright>
 
     <legalnotice>
@@ -46,21 +38,22 @@
   </bookinfo>
 
   <chapter>
-    <title>GUPnP DLNA</title>
-
-    <para>
-      GUPnP DLNA is a set of utility APIs to simplify DLNA-specific bits of
-      MediaServer implementations, such as DLNA media profile guessing.
-    </para>
+    <title>GUPnP DLNA Metadata</title>
 
     <para>
-      Before using the GUPnP DLNA API, you must initialise GStreamer by calling
-      gst_init() or gst_init_check().
+      GUPnP DLNA Metadata is a set of APIs to create a metadata
+      extractor plugins used by GUPnP DLNA Profile Guesser to guess
+      the profile.
     </para>
 
-    <xi:include href="xml/gupnp-dlna-discoverer.xml"/>
     <xi:include href="xml/gupnp-dlna-information.xml"/>
-    <xi:include href="xml/gupnp-dlna-profile.xml"/>
+    <xi:include href="xml/gupnp-dlna-values.xml"/>
+    <xi:include href="xml/gupnp-dlna-audio-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-container-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-image-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-video-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-metadata-extractor.xml"/>
+    <xi:include href="xml/api-index-full.xml"/>
 
   </chapter>
 
diff --git a/doc/gupnp-dlna/Makefile.am b/doc/gupnp-dlna/Makefile.am
new file mode 100644
index 0000000..c2b887c
--- /dev/null
+++ b/doc/gupnp-dlna/Makefile.am
@@ -0,0 +1,92 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=gupnp-dlna
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=../../libgupnp-dlna
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=--deprecated-guards="GUPNP_DISABLE_DEPRECATED"
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS = \
+	--sgml-mode \
+	--output-format=xml \
+	--ignore-files="metadata metadata-backends profile-backends"
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS = \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gobject \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gmodule
+
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(top_srcdir)/libgupnp-dlna/*.h
+CFILE_GLOB=$(top_srcdir)/libgupnp-dlna/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES = \
+	metadata \
+	metadata-backends \
+	profile-backends \
+	gupnp-dlna-field-value.h \
+	gupnp-dlna-metadata-backend.h \
+	gupnp-dlna-profile-backend.h \
+	gupnp-dlna-profile-guesser-impl.h \
+	gupnp-dlna-profile-loader.h
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=../version.xml
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+INCLUDES=-I$(top_srcdir)
+GTKDOC_LIBS=$(top_builddir)/libgupnp-dlna/libgupnp-dlna-2.0.la
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
diff --git a/doc/dlna-profiles-example.xml b/doc/gupnp-dlna/dlna-profiles-example.xml
similarity index 100%
rename from doc/dlna-profiles-example.xml
rename to doc/gupnp-dlna/dlna-profiles-example.xml
diff --git a/doc/gupnp-dlna-docs.sgml b/doc/gupnp-dlna/gupnp-dlna-docs.sgml
similarity index 87%
rename from doc/gupnp-dlna-docs.sgml
rename to doc/gupnp-dlna/gupnp-dlna-docs.sgml
index 8465da4..a23c534 100644
--- a/doc/gupnp-dlna-docs.sgml
+++ b/doc/gupnp-dlna/gupnp-dlna-docs.sgml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
-<!ENTITY version SYSTEM "version.xml">
+<!ENTITY version SYSTEM "../version.xml">
 ]>
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
   <bookinfo>
@@ -21,6 +21,10 @@
       <year>2010</year>
       <holder>Nokia Corporation</holder>
     </copyright>
+    <copyright>
+      <year>2012</year>
+      <holder>Intel Corporation</holder>
+    </copyright>
 
     <legalnotice>
       <para>
@@ -53,14 +57,9 @@
       MediaServer implementations, such as DLNA media profile guessing.
     </para>
 
-    <para>
-      Before using the GUPnP DLNA API, you must initialise GStreamer by calling
-      gst_init() or gst_init_check().
-    </para>
-
-    <xi:include href="xml/gupnp-dlna-discoverer.xml"/>
-    <xi:include href="xml/gupnp-dlna-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-profile-guesser.xml"/>
     <xi:include href="xml/gupnp-dlna-profile.xml"/>
+    <xi:include href="xml/api-index-full.xml"/>
 
   </chapter>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]