adding support files for plugins documentation

Original commit message from CVS:
adding support files for plugins documentation
parent 856fbbfa
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:
......
# -*- 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()
......@@ -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) \
......
<?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>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment