+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:
--- /dev/null
+# -*- 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 = "&".join(line.split("&"))
+ line = "<".join(line.split("<"))
+ line = ">".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()
DOC_STAMPS = \
scan-build.stamp \
tmpl-build.stamp \
+ inspect-build.stamp \
sgml-build.stamp \
html-build.stamp \
$(srcdir)/tmpl.stamp \
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) \
--- /dev/null
+<?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>
projects / platform / upstream / gst-common.git / commitdiff