From: Stefan Kost Date: Tue, 15 Jun 2010 12:21:15 +0000 (+0300) Subject: docs: move gst-xmlinspect.py functionality to gstdoc-scanobj X-Git-Tag: upstream/20130618~123 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=57c89b71cb943b578df9dde18779f74b5f03fd19;p=platform%2Fupstream%2Fgst-common.git docs: move gst-xmlinspect.py functionality to gstdoc-scanobj gst-xmlinspect was causing a circular dependency (as it uses gst-python). It also caused and extra build step and double registry scan. --- diff --git a/gst-xmlinspect.py b/gst-xmlinspect.py deleted file mode 100644 index 2068420..0000000 --- a/gst-xmlinspect.py +++ /dev/null @@ -1,168 +0,0 @@ -# -*- 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 pygst -pygst.require('0.10') -import gst - -INDENT_SIZE = 2 - -# all templates - -PAD_TEMPLATE = """ - %(name)s - %(direction)s - %(presence)s -
%(details)s
-""" - -ELEMENT_TEMPLATE = """ - %(name)s - %(longname)s - %(class)s - %(description)s - %(author)s - -%(pads)s - -""" - -PLUGIN_TEMPLATE = """ - %(name)s - %(description)s - %(filename)s - %(basename)s - %(version)s - %(license)s - %(source)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_pad_template(pt, indent=0): - print "PAD TEMPLATE", pt.name_template - paddir = ("unknown","source","sink") - padpres = ("always","sometimes","request") - - d = { - 'name': xmlencode(pt.name_template), - 'direction': xmlencode(paddir[pt.direction]), - 'presence': xmlencode(padpres[pt.presence]), - 'details': xmlencode(pt.static_caps.string), - } - block = PAD_TEMPLATE % d - - offset = get_offset(indent) - return offset + ("\n" + offset).join(block.split("\n")) - -def output_element_factory(elf, indent=0): - print "ELEMENT", elf.get_name() - - padsoutput = [] - padtemplates = elf.get_static_pad_templates() - for padtemplate in padtemplates: - padsoutput.append(output_pad_template(padtemplate, indent)) - - 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()), - 'pads': "\n".join(padsoutput), - } - 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 = plugin.get_version() - - elements = {} - gst.debug('getting features for plugin %s' % plugin.get_name()) - registry = gst.registry_get_default() - features = registry.get_feature_list_by_plugin(plugin.get_name()) - gst.debug('plugin %s has %d features' % (plugin.get_name(), len(features))) - for feature in features: - if isinstance(feature, gst.ElementFactory): - elements[feature.get_name()] = feature - #gst.debug("got features") - - elementsoutput = [] - keys = elements.keys() - keys.sort() - for name in keys: - feature = elements[name] - elementsoutput.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()), - 'source': xmlencode(plugin.get_source()), - 'package': xmlencode(plugin.get_package()), - 'origin': xmlencode(plugin.get_origin()), - 'elements': "\n".join(elementsoutput), - } - block = PLUGIN_TEMPLATE % d - - offset = get_offset(indent) - return offset + ("\n" + offset).join(block.split("\n")) - -def main(): - if len(sys.argv) == 1: - sys.stderr.write("Please specify a source module to inspect") - sys.exit(1) - source = sys.argv[1] - - if len(sys.argv) > 2: - os.chdir(sys.argv[2]) - - registry = gst.registry_get_default() - all = registry.get_plugin_list() - for plugin in all: - gst.debug("inspecting plugin %s from source %s" % ( - plugin.get_name(), plugin.get_source())) - # this skips gstcoreelements, with bin and pipeline - if plugin.get_filename() is None: - continue - if plugin.get_source() != source: - continue - - filename = "plugin-%s.xml" % plugin.get_name() - handle = open(filename, "w") - handle.write(output_plugin(plugin)) - handle.close() - -main() diff --git a/gstdoc-scangobj b/gstdoc-scangobj index 0fc2b28..5e3f8ca 100755 --- a/gstdoc-scangobj +++ b/gstdoc-scangobj @@ -38,6 +38,7 @@ require "gtkdoc-common.pl"; # name of documentation module my $MODULE; my $OUTPUT_DIR; +my $INSPECT_DIR; my $PRINT_VERSION; my $PRINT_HELP; my $TYPE_INIT_FUNC="g_type_init ()"; @@ -49,10 +50,11 @@ my $TYPE_INIT_FUNC="g_type_init ()"; nogtkinit => \$NO_GTK_INIT, 'type-init-func' => \$TYPE_INIT_FUNC, 'output-dir' => \$OUTPUT_DIR, + 'inspect-dir' => \$INSPECT_DIR, 'version' => \$PRINT_VERSION, 'help' => \$PRINT_HELP); -GetOptions(\%optctl, "module=s", "source=s", "types:s", "output-dir:s", "nogtkinit", "type-init-func:s", "version", "help"); +GetOptions(\%optctl, "module=s", "source=s", "types:s", "output-dir:s", "inspect-dir:s", "nogtkinit", "type-init-func:s", "version", "help"); if ($NO_GTK_INIT) { # Do nothing. This just avoids a warning. @@ -74,6 +76,7 @@ if ($PRINT_HELP) { print "\n--types=FILE The name of the file to store the types in"; print "\n--type-init-func=FUNC The init function to call instead of g_type_init ()"; print "\n--output-dir=DIRNAME The directory where the results are stored"; + print "\n--inspect-dir=DIRNAME The directory where the plugin inspect data is stored"; print "\n--version Print the version of this program"; print "\n--help Print this help\n"; exit 0; @@ -135,6 +138,56 @@ $includes #endif GType *object_types = NULL; +static const gchar* +xmlprint (gint indent, const gchar *tag, const gchar *data) +{ + /* 20 spaces */ + gchar indent_str[] = " "; + static gchar str[1000]; + gchar conv[1000]; + gchar *s2 = conv; + + if (data) { + const gchar *s1 = data; + while (*s1) { + switch (*s1) { + case '<': + *s2++='&'; + *s2++='l'; + *s2++='t'; + *s2++=';'; + break; + case '>': + *s2++='&'; + *s2++='g'; + *s2++='t'; + *s2++=';'; + break; + case '&': + *s2++='&'; + *s2++='a'; + *s2++='m'; + *s2++='p'; + *s2++=';'; + break; + default: + *s2++ = *s1; + } + s1++; + } + } + *s2 = '\\0'; + + sprintf(str, "%s<%s>%s\\n", &indent_str[20-indent], tag, conv, tag); + return str; +} + +static gint +gst_feature_sort_compare (gconstpointer a, gconstpointer b) +{ + return strcmp (((GstPluginFeature *)a)->name, ((GstPluginFeature *)b)->name); +} + static GType * get_object_types (void) { @@ -145,14 +198,16 @@ get_object_types (void) GType type; gint i = 0; - + /* get a list of features from plugins in our source module */ plugins = gst_registry_get_plugin_list (gst_registry_get_default()); while (plugins) { - GList *features; + GList *features, *pads; GstPlugin *plugin; const gchar *source; + FILE *inspect = NULL; + gchar *inspect_name; plugin = (GstPlugin *) (plugins->data); plugins = g_list_next (plugins); @@ -163,9 +218,31 @@ get_object_types (void) } g_print ("plugin: %s source: %s\\n", plugin->desc.name, source); + inspect_name = g_strdup_printf ("$INSPECT_DIR" G_DIR_SEPARATOR_S "plugin-%s.xml", + plugin->desc.name); + inspect = fopen (inspect_name, "w"); + g_free (inspect_name); + + /* output plugin data */ + fputs ("\\n",inspect); + fputs (xmlprint(2, "name", plugin->desc.name),inspect); + fputs (xmlprint(2, "description", plugin->desc.description),inspect); + fputs (xmlprint(2, "filename", plugin->filename),inspect); + fputs (xmlprint(2, "basename", plugin->basename),inspect); + fputs (xmlprint(2, "version", plugin->desc.version),inspect); + fputs (xmlprint(2, "license", plugin->desc.license),inspect); + fputs (xmlprint(2, "source", plugin->desc.source),inspect); + fputs (xmlprint(2, "package", plugin->desc.package),inspect); + fputs (xmlprint(2, "origin", plugin->desc.origin),inspect); + fputs (" \\n", inspect); + features = gst_registry_get_feature_list_by_plugin (gst_registry_get_default (), plugin->desc.name); + + /* sort factories by feature->name */ + features = g_list_sort (features, gst_feature_sort_compare); + while (features) { GstPluginFeature *feature; feature = GST_PLUGIN_FEATURE (features->data); @@ -176,11 +253,43 @@ get_object_types (void) } if (GST_IS_ELEMENT_FACTORY (feature)) { + GstStaticPadTemplate *pt; + const gchar *pad_dir[] = { "unknown","source","sink" }; + const gchar *pad_pres[] = { "always","sometimes","request" }; + factory = GST_ELEMENT_FACTORY (feature); factories = g_list_prepend (factories, factory); + + /* output element data */ + fputs (" \\n", inspect); + fputs (xmlprint(6, "name", feature->name),inspect); + fputs (xmlprint(6, "longname", factory->details.longname),inspect); + fputs (xmlprint(6, "class", factory->details.klass),inspect); + fputs (xmlprint(6, "description", factory->details.description),inspect); + fputs (xmlprint(6, "author", factory->details.author),inspect); + fputs (" \\n", inspect); + + /* output pad-template data */ + pads =(GList *) gst_element_factory_get_static_pad_templates (factory); + while (pads) { + pt = (GstStaticPadTemplate *)pads->data; + + fputs (" \\n", inspect); + fputs (xmlprint(10, "name", pt->name_template),inspect); + fputs (xmlprint(10, "direction", pad_dir[pt->direction]),inspect); + fputs (xmlprint(10, "presence", pad_pres[pt->presence]),inspect); + fputs (xmlprint(10, "details", pt->static_caps.string),inspect); + fputs (" \\n", inspect); + + pads = g_list_next (pads); + } + fputs (" \\n \\n", inspect); } features = g_list_next (features); } + + fputs (" \\n\\n", inspect); + fclose (inspect); } g_message ("number of element factories: %d", g_list_length (factories)); @@ -1633,7 +1742,9 @@ system($command) == 0 or die "Linking of scanner failed: $!\n"; print "gtk-doc: Running scanner $MODULE-scan\n"; system("sh -c ./$MODULE-scan") == 0 or die "Scan failed: $!\n"; -unlink "./$MODULE-scan.c", "./$MODULE-scan.o", "./$MODULE-scan.lo", "./$MODULE-scan"; +if (!defined($ENV{"GTK_DOC_KEEP_INTERMEDIATE"})) { + unlink "./$MODULE-scan.c", "./$MODULE-scan.o", "./$MODULE-scan.lo", "./$MODULE-scan"; +} #&UpdateFileIfChanged ($old_signals_filename, $new_signals_filename, 0); &UpdateFileIfChanged ($old_hierarchy_filename, $new_hierarchy_filename, 0); diff --git a/gtk-doc-plugins.mak b/gtk-doc-plugins.mak index 7214411..9d57449 100644 --- a/gtk-doc-plugins.mak +++ b/gtk-doc-plugins.mak @@ -14,7 +14,6 @@ help: # update the stuff maintained by doc maintainers update: - $(MAKE) inspect-update $(MAKE) scanobj-update # We set GPATH here; this gives us semantics for GNU make @@ -96,6 +95,20 @@ CLEANFILES = \ if ENABLE_GTK_DOC all-local: html-build.stamp +### inspect GStreamer plug-ins; done by documentation maintainer ### + +# 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_SYSTEM_PATH= \ + GST_PLUGIN_PATH=$(top_builddir)/gst:$(top_builddir)/sys:$(top_builddir)/ext:$(top_builddir)/plugins:$(top_builddir)/src:$(top_builddir)/gnl \ + GST_REGISTRY=$(INSPECT_REGISTRY) \ + $(INSPECT_EXTRA_ENVIRONMENT) + +# update the element and plugin XML descriptions; store in inspect/ +inspect: + mkdir inspect + #### scan gobjects; done by documentation maintainer #### scanobj-update: -rm scanobj-build.stamp @@ -108,7 +121,7 @@ scanobj-update: # TODO: finish elite script that updates the output files of this step # instead of rewriting them, so that multiple maintainers can generate # a collective set of args and signals -scanobj-build.stamp: $(SCANOBJ_DEPS) $(basefiles) +scanobj-build.stamp: $(SCANOBJ_DEPS) $(basefiles) inspect @echo '*** Scanning GObjects ***' if test x"$(srcdir)" != x. ; then \ for f in $(SCANOBJ_FILES); \ @@ -121,7 +134,7 @@ scanobj-build.stamp: $(SCANOBJ_DEPS) $(basefiles) CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" \ LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ $(GST_DOC_SCANOBJ) --type-init-func="gst_init(NULL,NULL)" \ - --module=$(DOC_MODULE) --source=$(PACKAGE) && \ + --module=$(DOC_MODULE) --source=$(PACKAGE) --inspect-dir="inspect" && \ $(PYTHON) \ $(top_srcdir)/common/scangobj-merge.py $(DOC_MODULE); \ fi @@ -130,40 +143,8 @@ scanobj-build.stamp: $(SCANOBJ_DEPS) $(basefiles) $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(SCANOBJ_FILES_O): scan-build.stamp @true -### inspect GStreamer plug-ins; done by documentation maintainer ### - -# 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_SYSTEM_PATH= \ - GST_PLUGIN_PATH=$(top_builddir)/gst:$(top_builddir)/sys:$(top_builddir)/ext:$(top_builddir)/plugins:$(top_builddir)/src:$(top_builddir)/gnl \ - GST_REGISTRY=$(INSPECT_REGISTRY) \ - $(INSPECT_EXTRA_ENVIRONMENT) - -# update the element and plugin XML descriptions; store in inspect/ -inspect: - mkdir inspect - -inspect-update: inspect - -rm -f $(INSPECT_REGISTRY) inspect-build.stamp - $(MAKE) inspect-build.stamp - -# FIXME: inspect.stamp should be written to by gst-xmlinspect.py -# IF the output changed; see gtkdoc-mktmpl -inspect-build.stamp: - @echo '*** Rebuilding plugin inspection files ***' - if test x"$(srcdir)" != x. ; then \ - cp $(srcdir)/inspect.stamp . ; \ - cp $(srcdir)/inspect-build.stamp . ; \ - else \ - $(INSPECT_ENVIRONMENT) $(PYTHON) \ - $(top_srcdir)/common/gst-xmlinspect.py $(PACKAGE) inspect && \ - echo -n "timestamp" > inspect.stamp && \ - touch inspect-build.stamp; \ - fi - ### scan headers; done on every build ### -scan-build.stamp: $(HFILE_GLOB) $(EXTRA_HFILES) $(basefiles) scanobj-build.stamp inspect-build.stamp +scan-build.stamp: $(HFILE_GLOB) $(EXTRA_HFILES) $(basefiles) scanobj-build.stamp if test "x$(top_srcdir)" != "x$(top_builddir)" && \ test -d "$(top_builddir)/gst"; \ then \