adding support files for plugins documentation

Original commit message from CVS:
adding support files for plugins documentation

4 files changed, 236 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index a6de9c3..29b8b92 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2005-08-15  Thomas Vander Stichele  <thomas at apestaart dot org>
+
+	* gst-xmlinspect.py:
+	  a first stab at inspecting plugins and outputting an xml description
+	* gtk-doc-plugins.mak:
+	  a gtk-doc using snippet for plugins documentation
+	* plugins.xsl:
+	  a stylesheet to convert gst-xmlinspect.py output to docbook output
+	  for inclusion in the gtk-doc stuff
+
 2005-07-20  Ronald S. Bultje  <rbultje@ronald.bitfreak.net>
 
 	* m4/gst-doc.m4:
diff --git a/gst-xmlinspect.py b/gst-xmlinspect.py
new file mode 100644
index 0000000..d813d27
--- /dev/null
+++ b/gst-xmlinspect.py
@@ -0,0 +1,105 @@
+# -*- Mode: Python -*-
+# vi:si:et:sw=4:sts=4:ts=4
+
+"""
+examine all plugins and elements and output xml documentation for them
+used as part of the plugin documentation build
+"""
+
+import sys
+import os
+import gst
+
+INDENT_SIZE = 2
+
+# all templates
+ELEMENT_TEMPLATE = """<element>
+  <name>%(name)s</name>
+  <longname>%(longname)s</longname>
+  <class>%(class)s</class>
+  <description>%(description)s</description>
+  <author>%(author)s</author>
+</element>"""
+
+PLUGIN_TEMPLATE = """<plugin>
+  <name>%(name)s</name>
+  <description>%(description)s</description>
+  <filename>%(filename)s</filename>
+  <basename>%(basename)s</basename>
+  <version>%(version)s</version>
+  <license>%(license)s</license>
+  <package>%(package)s</package>
+  <origin>%(origin)s</origin>
+  <elements>
+%(elements)s
+  </elements>
+</plugin>"""
+
+def xmlencode(line):
+    """
+    Replace &, <, and >
+    """
+    line = "&amp;".join(line.split("&"))
+    line = "&lt;".join(line.split("<"))
+    line = "&gt;".join(line.split(">"))
+    return line
+
+def get_offset(indent):
+    return " " * INDENT_SIZE * indent
+
+def output_element_factory(elf, indent=0):
+    print  "ELEMENT", elf.get_name()
+    d = {
+        'name':        xmlencode(elf.get_name()),
+        'longname':    xmlencode(elf.get_longname()),
+        'class':       xmlencode(elf.get_klass()),
+        'description': xmlencode(elf.get_description()),
+        'author':      xmlencode(elf.get_author()),
+    }
+    block = ELEMENT_TEMPLATE % d
+    
+    offset = get_offset(indent)
+    return offset + ("\n" + offset).join(block.split("\n"))
+
+
+def output_plugin(plugin, indent=0):
+    print "PLUGIN", plugin.get_name()
+    version = ".".join([str(i) for i in plugin.get_version()])
+    
+    elements = []
+    for feature in plugin.get_feature_list():
+        if isinstance(feature, gst.ElementFactory):
+            elements.append(output_element_factory(feature, indent + 2))
+        
+    filename = plugin.get_filename()
+    basename = filename
+    if basename:
+        basename = os.path.basename(basename)
+    d = {
+        'name':        xmlencode(plugin.get_name()),
+        'description': xmlencode(plugin.get_description()),
+        'filename':    filename,
+        'basename':    basename,
+        'version':     version,
+        'license':     xmlencode(plugin.get_license()),
+        'package':     xmlencode(plugin.get_package()),
+        'origin':      xmlencode(plugin.get_origin()),
+        'elements': "\n".join(elements),
+    }
+    block = PLUGIN_TEMPLATE % d
+    
+    offset = get_offset(indent)
+    return offset + ("\n" + offset).join(block.split("\n"))
+
+def main():
+    if sys.argv[1]:
+        os.chdir(sys.argv[1])
+
+    all = gst.registry_pool_plugin_list()
+    for plugin in all:
+        filename = "plugin-%s.xml" % plugin.get_name()
+        handle = open(filename, "w")
+        handle.write(output_plugin(plugin))
+        handle.close()
+
+main()
diff --git a/gtk-doc-plugins.mak b/gtk-doc-plugins.mak
index fd1ad12..df99994 100644
--- a/gtk-doc-plugins.mak
+++ b/gtk-doc-plugins.mak
@@ -25,6 +25,7 @@ EXTRA_DIST = 				\
 DOC_STAMPS =				\
 	scan-build.stamp		\
 	tmpl-build.stamp		\
+	inspect-build.stamp		\
 	sgml-build.stamp		\
 	html-build.stamp		\
 	$(srcdir)/tmpl.stamp		\
@@ -93,11 +94,39 @@ tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections
 tmpl.stamp: tmpl-build.stamp
 	@true
 
+#### inspect stuff ####
+# this is stuff that should be built/updated manually by people that work
+# on docs
+
+# only look at the plugins in this module when building inspect .xml stuff
+INSPECT_REGISTRY=$(top_builddir)/docs/plugins/inspect-registry.xml
+INSPECT_ENVIRONMENT=\
+        GST_PLUGIN_PATH_ONLY=yes \
+        GST_PLUGIN_PATH=$(top_builddir)/gst:$(top_builddir)/sys:$(top_builddir)/ext \
+        GST_REGISTRY=$(INSPECT_REGISTRY)
+
+
+# update the element and plugin XML descriptions; store in inspect/
+inspect:
+	mkdir inspect
+
+inspect-build.stamp: inspect
+	$(INSPECT_ENVIRONMENT) $(PYTHON) \
+		$(top_srcdir)/common/gst-xmlinspect.py inspect
+	touch inspect-build.stamp
+
+inspect.stamp: inspect-build.stamp
+	@true
+
 #### xml ####
 
 ### FIXME: make this error out again when docs are fixed for 0.9
-sgml-build.stamp: tmpl.stamp $(CFILE_GLOB)
+# first convert inspect/*.xml to xml
+sgml-build.stamp: tmpl.stamp inspect.stamp $(CFILE_GLOB)
 	@echo '*** Building XML ***'
+	@-mkdir -p xml
+	@for a in inspect/*.xml; do \
+            xsltproc $(top_srcdir)/common/plugins.xsl $$a > xml/`basename $$a`; done
 	gtkdoc-mkdb \
 		--module=$(DOC_MODULE) \
 		--source-dir=$(DOC_SOURCE_DIR) \
diff --git a/plugins.xsl b/plugins.xsl
new file mode 100644
index 0000000..15ade5f
--- /dev/null
+++ b/plugins.xsl
@@ -0,0 +1,91 @@
+<?xml version='1.0'?> <!--*- mode: xml -*-->
+
+<xsl:stylesheet
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:exsl="http://exslt.org/common"
+  extension-element-prefixes="exsl"
+  version="1.0">
+<xsl:output method="xml" indent="yes"
+            doctype-public ="-//OASIS//DTD DocBook XML V4.1.2//EN"
+            doctype-system = "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/> 
+
+  <xsl:template match="element">
+    <xsl:element name="varlistentry">
+      <xsl:element name="term">
+        <xsl:element name="link">
+          <xsl:attribute name="linkend">gst-plugins-base-plugins-<xsl:value-of select="name"/></xsl:attribute>
+          <xsl:value-of select="name" />
+        </xsl:element>
+      </xsl:element>
+      <xsl:element name="listitem">
+        <xsl:element name="simpara"><xsl:value-of select="description" /></xsl:element>
+      </xsl:element>
+    </xsl:element>
+    <xsl:variable name="name"><xsl:copy-of select="name"/></xsl:variable>
+    <!-- here we write an element-(name)-details.xml file for the element -->
+    <exsl:document href="{concat ('xml/element-', $name, '-details.xml')}" method="xml" indent="yes">
+      <xsl:element name="variablelist">
+        <xsl:element name="varlistentry">
+          <xsl:element name="term">author</xsl:element>
+          <xsl:element name="listitem">
+            <xsl:element name="simpara"><xsl:value-of select="author" /></xsl:element>
+          </xsl:element>
+        </xsl:element>
+      </xsl:element>
+
+    </exsl:document>
+  </xsl:template>
+
+  <xsl:template match="plugin">
+    <xsl:element name="refentry">
+      <xsl:attribute name="id">gst-plugins-base-plugins-plugin-<xsl:value-of select="name"/></xsl:attribute>
+
+      <xsl:element name="refmeta">
+        <xsl:element name="refentrytitle">
+          <xsl:value-of select="name"/>
+        </xsl:element>
+        <xsl:element name="manvolnum">3</xsl:element>
+        <xsl:element name="refmiscinfo">FIXME Library</xsl:element>
+      </xsl:element> <!-- refmeta -->
+
+      <xsl:element name="refnamediv">
+        <xsl:element name="refname">
+          <xsl:element name="anchor">
+            <xsl:attribute name="id">plugin-<xsl:value-of select="name"/></xsl:attribute>
+            <xsl:value-of select="name"/>
+          </xsl:element>
+        </xsl:element>
+  
+        <xsl:element name="refpurpose">
+          <xsl:value-of select="description"/>
+        </xsl:element>
+      </xsl:element>
+
+      <xsl:element name="refsect1">
+        <xsl:element name="title">Plugin Information</xsl:element>
+        <xsl:element name="variablelist">
+          <xsl:element name="varlistentry">
+            <xsl:element name="term">filename</xsl:element>
+            <xsl:element name="listitem">
+              <xsl:element name="simpara"><xsl:value-of select="basename" /></xsl:element>
+            </xsl:element>
+          </xsl:element>
+        </xsl:element>
+      </xsl:element>
+
+      <xsl:element name="refsect1">
+        <xsl:element name="title">Elements</xsl:element>
+        <!-- process all elements -->
+        <xsl:element name="variablelist">
+          <xsl:apply-templates select="elements"/>
+        </xsl:element>
+      </xsl:element>
+
+    </xsl:element>
+
+  </xsl:template>
+
+  <!-- ignore -->
+  <xsl:template match="gst-plugin-paths" />
+
+</xsl:stylesheet>