GNOME.org
 

[rygel] docs: Add overview documentation.

commit 66928dcac0fe53ed591a4b34fe6ef6009bba965d
Author: Murray Cumming <murrayc murrayc com>
Date:   Fri Oct 12 12:59:28 2012 +0200

    docs: Add overview documentation.
    
    These mention the most interesting classes and show the example code
    from examples/.

 doc/reference/doc-build.am                         |    4 ++-
 .../librygel-core/gtkdoc/librygel-core-docs.xml    |    9 +++++-
 doc/reference/librygel-core/gtkdoc/overview.xml    |   25 ++++++++++++++
 .../gtkdoc/librygel-renderer-gst-docs.xml          |    9 +++++-
 .../librygel-renderer-gst/gtkdoc/overview.xml      |   34 ++++++++++++++++++++
 .../gtkdoc/librygel-renderer-docs.xml              |    9 +++++-
 .../librygel-renderer/gtkdoc/overview.xml          |   23 +++++++++++++
 .../gtkdoc/librygel-server-docs.xml                |    9 +++++-
 doc/reference/librygel-server/gtkdoc/overview.xml  |   33 +++++++++++++++++++
 examples/standalone-renderer.c                     |    2 +-
 .../rygel-playbin-renderer.vala                    |    2 +-
 src/librygel-server/rygel-media-server.vala        |    2 +-
 12 files changed, 153 insertions(+), 8 deletions(-)
---
diff --git a/doc/reference/doc-build.am b/doc/reference/doc-build.am
index 075196b..5221f4d 100644
--- a/doc/reference/doc-build.am
+++ b/doc/reference/doc-build.am
@@ -26,7 +26,9 @@ valadoc-gen: $(VALA_SOURCE_FILES_WITH_PATHS)
 # Avoid regeneration of the html if none of its dependencies have changed:
 gtkdoc/html/index.html: gtkdoc-gen
 
-RYGEL_GTKDOC_DOCS_XML = $(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/lib$(RYGEL_DOCBUILD_MODULE)-docs.xml
+RYGEL_GTKDOC_DOCS_XML = \
+	$(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/lib$(RYGEL_DOCBUILD_MODULE)-docs.xml \
+	$(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/overview.xml
 
 gtkdoc-gen: $(VALA_SOURCE_FILES_WITH_PATHS) $(RYGEL_GTKDOC_DOCS_XML)
 	@rm -rf gtkdoc/html
diff --git a/doc/reference/librygel-core/gtkdoc/librygel-core-docs.xml b/doc/reference/librygel-core/gtkdoc/librygel-core-docs.xml
index 361907e..b256ab5 100644
--- a/doc/reference/librygel-core/gtkdoc/librygel-core-docs.xml
+++ b/doc/reference/librygel-core/gtkdoc/librygel-core-docs.xml
@@ -14,9 +14,16 @@
     </releaseinfo>
   </bookinfo>
 
+  <!-- This is hand written: -->
+  <preface>
+    <title>Overview</title>
+    <xi:include href="overview.xml"/>
+  </preface>
+
+  <!-- These are generated: -->
   <chapter>
     <title>librygel-core API Reference</title>
-        <xi:include href="xml/rygel-connection-manager.xml"/>
+    <xi:include href="xml/rygel-connection-manager.xml"/>
     <xi:include href="xml/rygel-configuration.xml"/>
     <xi:include href="xml/rygel-log-handler.xml"/>
     <xi:include href="xml/rygel-resource-info.xml"/>
diff --git a/doc/reference/librygel-core/gtkdoc/overview.xml b/doc/reference/librygel-core/gtkdoc/overview.xml
new file mode 100644
index 0000000..85fcb65
--- /dev/null
+++ b/doc/reference/librygel-core/gtkdoc/overview.xml
@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry 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'">
+]>
+
+<section id="overview">
+
+<para>
+librygel-core is part of the <ulink url="http://rygel-project.org/";>Rygel</ulink> project.
+</para>
+
+<para>
+This library allows in-process use of much of the DLNA and UPnP knowledge coded in Rygel.
+It is used by the <ulink url="http://rygel-project.org/";>Rygel</ulink> server, 
+<ulink url="http://developer.gnome.org/librygel-renderer/unstable/";>librygel-renderer</ulink>.
+It is also used by <ulink url="https://live.gnome.org/Rygel/Korva";>Korva</ulink>, which is in
+turn used by the <ulink href="http://jensge.org/helium-a-m-dmc-for-your-n9/";>Helium</ulink> UPnP control point.
+</para>
+
+<para>
+librygel-renderer-gst is licensed under the GNU Lesser General Public License (LGPL).
+</para>
+
+</section>
diff --git a/doc/reference/librygel-renderer-gst/gtkdoc/librygel-renderer-gst-docs.xml b/doc/reference/librygel-renderer-gst/gtkdoc/librygel-renderer-gst-docs.xml
index 7981bf3..84eb006 100644
--- a/doc/reference/librygel-renderer-gst/gtkdoc/librygel-renderer-gst-docs.xml
+++ b/doc/reference/librygel-renderer-gst/gtkdoc/librygel-renderer-gst-docs.xml
@@ -14,13 +14,20 @@
     </releaseinfo>
   </bookinfo>
 
+  <!-- This is hand written: -->
+  <preface>
+    <title>Overview</title>
+    <xi:include href="overview.xml"/>
+  </preface>
+
+    <!-- These are generated: -->
   <chapter>
     <title>librygel-renderer-gst API Reference</title>
     <xi:include href="xml/rygel-playbin-renderer.xml"/>
     <xi:include href="xml/rygel-playbin-player.xml"/>
     <xi:include href="xml/rygel-playbin-plugin.xml"/>
-
   </chapter>
+
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>
diff --git a/doc/reference/librygel-renderer-gst/gtkdoc/overview.xml b/doc/reference/librygel-renderer-gst/gtkdoc/overview.xml
new file mode 100644
index 0000000..c2e05ea
--- /dev/null
+++ b/doc/reference/librygel-renderer-gst/gtkdoc/overview.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry 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'">
+]>
+
+<section id="overview">
+
+<para>
+librygel-renderer-gst is part of the <ulink url="http://rygel-project.org/";>Rygel</ulink> project.
+</para>
+
+<para>
+This library may be used to create UPnP or DLNA Renderers using GStreamer.
+The <link linkend="RygelPlaybinRenderer">RygelPlaybinRenderer</link> may
+wrap an existing GStreamer playbin or create its own.
+</para>
+
+<!-- TODO: Find a way to mention this C example code in the RygelPlaybinRenderer valadoc comments instead. -->
+<para>
+This example program shows how to instantiate the renderer then configure its GStreamer playbin element
+and connect it to a network interface.
+</para>
+<programlisting role="C">
+  <xi:include  href="../../../../examples/standalone-renderer.c"
+    parse="text"
+    xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</programlisting>
+
+<para>
+librygel-renderer-gst is licensed under the GNU Lesser General Public License (LGPL).
+</para>
+
+</section>
diff --git a/doc/reference/librygel-renderer/gtkdoc/librygel-renderer-docs.xml b/doc/reference/librygel-renderer/gtkdoc/librygel-renderer-docs.xml
index affaebc..408316c 100644
--- a/doc/reference/librygel-renderer/gtkdoc/librygel-renderer-docs.xml
+++ b/doc/reference/librygel-renderer/gtkdoc/librygel-renderer-docs.xml
@@ -14,9 +14,16 @@
     </releaseinfo>
   </bookinfo>
 
+  <!-- This is hand written: -->
+  <preface>
+    <title>Overview</title>
+    <xi:include href="overview.xml"/>
+  </preface>
+
+  <!-- These are generated: -->
   <chapter>
     <title>librygel-renderer API Reference</title>
-        <xi:include href="xml/rygel-media-renderer-plugin.xml"/>
+    <xi:include href="xml/rygel-media-renderer-plugin.xml"/>
     <xi:include href="xml/rygel-media-renderer.xml"/>
     <xi:include href="xml/rygel-media-player.xml"/>
 
diff --git a/doc/reference/librygel-renderer/gtkdoc/overview.xml b/doc/reference/librygel-renderer/gtkdoc/overview.xml
new file mode 100644
index 0000000..9ff83d3
--- /dev/null
+++ b/doc/reference/librygel-renderer/gtkdoc/overview.xml
@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry 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'">
+]>
+
+<section id="overview">
+
+<para>
+librygel-renderer is part of the <ulink url="http://rygel-project.org/";>Rygel</ulink> project.
+</para>
+
+<para>
+This library may be used to create UPnP or DLNA Renderers.
+For instance, librygel-renderer-gst uses librygel-renderer with GStreamer 
+to implement its RygelPlaybinRenderer renderer.
+</para>
+
+<para>
+librygel-renderer-gst is licensed under the GNU Lesser General Public License (LGPL).
+</para>
+
+</section>
diff --git a/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml b/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
index 933a7ae..568beaf 100644
--- a/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
+++ b/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
@@ -14,9 +14,16 @@
     </releaseinfo>
   </bookinfo>
 
+  <!-- This is hand written: -->
+  <preface>
+    <title>Overview</title>
+    <xi:include href="overview.xml"/>
+  </preface>
+
+  <!-- These are generated: -->
   <chapter>
     <title>librygel-server API Reference</title>
-        <xi:include href="xml/rygel-image-item.xml"/>
+    <xi:include href="xml/rygel-image-item.xml"/>
     <xi:include href="xml/rygel-photo-item.xml"/>
     <xi:include href="xml/rygel-media-item.xml"/>
     <xi:include href="xml/rygel-data-source.xml"/>
diff --git a/doc/reference/librygel-server/gtkdoc/overview.xml b/doc/reference/librygel-server/gtkdoc/overview.xml
new file mode 100644
index 0000000..4c6cc85
--- /dev/null
+++ b/doc/reference/librygel-server/gtkdoc/overview.xml
@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry 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'">
+]>
+
+<section id="overview">
+
+<para>
+librygel-server is part of the <ulink url="http://rygel-project.org/";>Rygel</ulink> project.
+</para>
+
+<para>
+This library may be used to create UPnP or DLNA servers via its
+The <link linkend="RygelMediaServer">RygelMediaServer</link>.
+</para>
+
+<!-- TODO: Find a way to mention this C example code in the RygelMediaServer valadoc comments instead. -->
+<para>
+This example program shows how to fill a container with media items and then instantiate a server to serve 
+them.
+</para>
+<programlisting role="C">
+  <xi:include  href="../../../../examples/standalone-server.c"
+    parse="text"
+    xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</programlisting>
+
+<para>
+librygel-server is licensed under the GNU Lesser General Public License (LGPL).
+</para>
+
+</section>
diff --git a/examples/standalone-renderer.c b/examples/standalone-renderer.c
index 2703499..1cfc8d1 100644
--- a/examples/standalone-renderer.c
+++ b/examples/standalone-renderer.c
@@ -21,7 +21,7 @@
  */
 
 /*
- * Demo application for librygel-renderer.
+ * Demo application for librygel-renderer-gst.
  *
  * Creates a simple stand-alone UPnP renderer that renders any visual content
  * in ASCII-art using GStreamer's cacasink element.
diff --git a/src/librygel-renderer-gst/rygel-playbin-renderer.vala b/src/librygel-renderer-gst/rygel-playbin-renderer.vala
index 012e11b..9438a3e 100644
--- a/src/librygel-renderer-gst/rygel-playbin-renderer.vala
+++ b/src/librygel-renderer-gst/rygel-playbin-renderer.vala
@@ -56,7 +56,7 @@ internal class Rygel.Playbin.WrappingPlugin : Rygel.MediaRendererPlugin {
  * to be controlled by a control point and to retrieve data streams via that
  * network interface.
  *
- * See the standalone-renderer.c example.
+ * See the example code in the <link linkend="overview">overview</link>.
  */
 public class Rygel.Playbin.Renderer : Rygel.MediaDevice {
     /**
diff --git a/src/librygel-server/rygel-media-server.vala b/src/librygel-server/rygel-media-server.vala
index 00e88da..afa61f3 100644
--- a/src/librygel-server/rygel-media-server.vala
+++ b/src/librygel-server/rygel-media-server.vala
@@ -31,7 +31,7 @@ internal class Plugin : Rygel.MediaServerPlugin {
  * Call rygel_media_device_add_interface() on the RygelMediaServer to allow it
  * to serve media via that network interface.
  *
- * See the standalone-server.c example.
+ * See the example code in the <link linkend="overview">overview</link>.
  */
 public class Rygel.MediaServer : MediaDevice {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]