[gst-devel] element documentation

[Thomas Vander Stichele]

Hello everyone,

I worked a little on some ideas for generating documentation for
elements, as has been discussed various times in the past.

I've decided to go ahead and get started using gtk-doc to document
elements and their signals and properties.  I want to expand on that to
include more information.

I'm going to braindump my thoughts on where I want to go with this, so
you guys can offer suggestions.

a) we already agreed in the past that relevant information needs to be
extracted from the actual plugins - the .so files.  Bear in mind that
this information can easily be dynamic - see gst-ffmpeg, libvisual,
ladspa, ...

b) Since no single machine can ever build all plugins, it's impossible
to generate docs from scratch on one single machine.  Thus, output from
various machines needs to be commited to CVS in some form as part of the
documentation.  At this point, it seems most likely that this would
either be the sgml/ directory + the stuff that the gobject scanner
creates (.signals, .args, ...), or the xml/ directory, which is the
docbook stuff.

c) from this commited stuff, a complete set of docs can be built by
anyone.

d) so for the basics, the scan step would not be run on every build,
only by people that want to update docs.  the result of that would be
commited to cvs.  then the gtk-doc build gets short-circuited so that
people can use this commited data to build maybe the docbook and
definately the html.

e) At this point, I've put in some documentation for a few elements.
This also seems to work fine on stefan's machine.  I wrote a gobj
scanner that uses the registry instead of a list of _get_types
functions, and that seems to work fine.  I documented everything
straight in the C file, which thanks to Stefan's patches that are part
of gtk-doc works just fine.

f) The next step is to add additional information.  As a first try, it
would be nice to extract other stuff from the registry (short/long
description, categories) and somehow merge it into the scanner's output.
I am trying to figure out if it's easy to include extra .sgml or .xml
content as part of the gtk-doc build, but the .xml files for each
section get generated without an xmlns: entry for XInclude, and I don't
see a nice way to add that.  Any suggestions ?

g) after that, I'd like to add some additional documentation - plugins,
other features, ...
For this, it probably makes sense to write something that generates
additional .xml files, which then can be included from the main .sgml
file.

h) eventually it'd be good to have a separate module which collects all
xml files, and can build a general index across modules, so that you
don't have to know which module/tarball an element is in.  The
combination of all these docs can be put on the website.

That's about it for now. Let me know what you think.



Dave/Dina : future TV today ! - http://www.davedina.org/
<-*- thomas (dot) apestaart (dot) org -*->
Sometimes I wish I was you
so I'd know how it feels
to have me inside of you
<-*- thomas (at) apestaart (dot) org -*->
URGent, best radio on the net - 24/7 ! - http://urgent.fm/