From 6f36afb863ab8f16a6be2a9f068cefdee885317d Mon Sep 17 00:00:00 2001 From: Thomas Vander Stichele Date: Mon, 15 Aug 2005 14:20:19 +0000 Subject: [PATCH] adding support files for plugins documentation Original commit message from CVS: adding support files for plugins documentation --- ChangeLog | 10 +++++ gst-xmlinspect.py | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++ gtk-doc-plugins.mak | 31 +++++++++++++++- plugins.xsl | 91 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 236 insertions(+), 1 deletion(-) create mode 100644 gst-xmlinspect.py create mode 100644 plugins.xsl diff --git a/ChangeLog b/ChangeLog index a6de9c3..29b8b92 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2005-08-15 Thomas Vander Stichele + + * 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 * 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 = """ + %(name)s + %(longname)s + %(class)s + %(description)s + %(author)s +""" + +PLUGIN_TEMPLATE = """ + %(name)s + %(description)s + %(filename)s + %(basename)s + %(version)s + %(license)s + %(package)s + %(origin)s + +%(elements)s + +""" + +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() 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 @@ + + + + + + + + + + gst-plugins-base-plugins- + + + + + + + + + + + + + author + + + + + + + + + + + + gst-plugins-base-plugins-plugin- + + + + + + 3 + FIXME Library + + + + + + plugin- + + + + + + + + + + + Plugin Information + + + filename + + + + + + + + + Elements + + + + + + + + + + + + + + -- 2.7.4