docutils based docs

Original commit message from CVS:
docutils based docs

.gitignore

@@ -2,6 +2,7 @@ Makefile
 Makefile.in
 gst-python.spec
 aclocal.m4
+autoregen.sh
 config.cache
 config.guess
 config.h

AUTHORS

@@ -1,11 +1,39 @@
-gst-python authors:
+.. gst-python AUTHORS
+.. This file writen with docutils markup (http://docutils.sourceforge.net/)
 
-David I. Lehn  <dlehn@users.sourceforge.net>
+Contact
+=======
 
+Please feel free to contact the developers.  They hang out on IRC_ and the
+mailing lists_.
+
+.. _IRC: http://gstreamer.net/dev/
+.. _lists: http://gstreamer.net/contact/lists.php
+
+Authors
+=======
+
+Maintainer
+----------
+
+* David I. Lehn  <dlehn@users.sourceforge.net>
+
+Contributions
+-------------
+
+Patches, suggestions, and other help:
+
+* Kenichi Sato <ksato@users.sourceforge.net>)
 
 Much of the framework for gst-python stolen from gtk and gconf bindings by:
 
-James Henstridge  <james@daa.com.au>
+* James Henstridge  <james@daa.com.au>
-Johan Dahlin  <jdahlin@telia.com>
+* Johan Dahlin  <jdahlin@telia.com>
-Matt Wilson  <msw@redhat.com>
+* Matt Wilson  <msw@redhat.com>
-and many more...
+* and many more...
+
+GStreamer
+---------
+
+And of course, none of this would be possible without the extreme hacker mojo
+of the whole GStreamer crew!

ChangeLog

@@ -4,6 +4,9 @@
 
 	* configure.ac, Makefile.am, pkgconfig/*: add pkgconfig support
 
+	* AUTHORS, NEWS, README, TODO, docs/HEAD.in, docs/Makefile.am,
+	docs/docutils.conf, docs/gst-python.css: docutils based docs
+
 2003-06-11  Thomas Vander Stichele <thomas at apestaart dot org>
 
 	* gst-python.spec.in: fix

NEWS

@@ -0,0 +1,10 @@
+.. gst-python NEWS
+.. This file writen with docutils markup (http://docutils.sourceforge.net/)
+
+News
+====
+
+2003-06-xx - 0.1.0 released
+---------------------------
+
+* first release

README

@@ -1,36 +1,186 @@
-gst-python
+.. gst-python README
-==========
+.. This file writen with docutils markup (http://docutils.sourceforge.net/)
 
-This is gst-python, the Python[1] bindings for the GStreamer[2] project.
+About
+=====
 
-For further help ask on a GStreamer mailing list or IRC.
+This is **gst-python**, the Python_ bindings for the GStreamer_ project.  The
+bindings provide access to almost all of the GStreamer C API through an object
+oriented Python API.
 
-[1] http://www.python.org/
+.. _Python: http://www.python.org/
-[2] http://www.gstreamer.net/
+.. _GStreamer: http://www.gstreamer.net/
 
 
-build/install
+Requirements
--------------
+============
 
-For build and install information please refer to the "INSTALL" file.
+* Python_ 2.2
-Installation is optional, gst-python can be used from the build directory.
+* GStreamer_ 0.6.0
+* PyGTK_ 1.99.14
+
+.. _PyGTK: http://www.daa.com.au/~james/pygtk/
 
 
-using
+Build/Install
------
+=============
+
+For build and install information please refer to the "``INSTALL``" file.
+Installation is optional, gst-python can be used from the build directory.  The
+quick instructions: build and install PyGTK and GStreamer then build
+gst-python::
+
+ $ ./configure && make
+
+
+Using
+=====
 
 You either need to install the package or add the root directory to your
-Python path.
+Python path::
 
  $ export PYTHONPATH=$PYTHONPATH:`pwd`
 
-Try running an example:
+Try running examples::
 
  $ cd examples/gstreamer/
  $ python cp.py <input file> <output file>
+ $ cmp <input file> <output file>
+ $ python vorbisplay.py <a vorbis file>
 
 
-documentation
+Documentation
--------------
+=============
 
-The examples are the best documentation for now.  Read them.
+General/API
+-----------
+
+The gst-python bindings are directly generated from the GStreamer headers.
+Look at the GStreamer documentation_ for general API and programming issues.
+In most cases the GStreamer classes and boxed types map directly to Python
+classes.  The function-based methods also map onto Python object methods.
+
+.. _documentation: http://www.gstreamer.net/docs/
+
+
+Divergence From C API
+---------------------
+
+Due to the nature of C and Python some of the GStreamer API is handled slightly
+different in Python than C.  There are a few of the GStreamer C functions that
+are not yet provided in gst-python.  These are mostly related to creating
+`Python Elements`_.  A few others remain that return GList* or return values in
+their parameters.  These have been wrapped as needed.  Please file a bug_ if
+you need one of the unwrapped functions.
+
+API changes:
+
+* ``gst_props_entry_get_type`` is accessed through
+  ``PropsEntry.get_props_type()``.  This is due to the ``_get_type`` function
+  extention being normally used for ``GType`` access and is inaccessable
+  otherwise.
+
+* Special `Pipeline Iteration`_ support through the following functions:
+
+  * ``add_iterate_bin(bin) -> id``: used to iterate a bin with a C idle loop
+    callback instead of a Python callback.
+  * ``remove_iterate_bin(id)``: used to remove the ``add_iterate_bin``
+    idle loop callback id.
+  * ``iterate_bin_all(bin)``: releases locks, calls ``gst_bin_iterate``
+    until it returns 0, reacquires locks and completes
+
+* `Python Elements`_ support through the following horribly inefficient
+  functions:
+
+  * ``Buffer.get_data() -> string``: converts buffer data to a string and
+     returns it.
+  * ``Buffer.set_data(string)``: sets the buffer data from a string.
+
+
+Examples
+--------
+
+The best documentation right now is the examples in
+"``./examples/gstreamer/``".  Read them.
+
+
+Threads
+-------
+
+Threading is a tricky subject for gst-python.  There are a few lock you need to
+be aware of:
+
+* GIL
+
+  The CPython interpreter is single threaded.  Code execution in the
+  interpreter is protected by a Global Interpreter Lock (GIL).  This means that
+  C code can run in other threads in parallel but only one thread will be
+  running Python code at any one point.  Most of this is handled internally by
+  means of locking and unlocking the GIL at appropriate times.  Callback code
+  and other various code paths between Python and C *should* be setup to do
+  proper GIL handling.
+  
+  However, it is possible that you may encounter a situation where proper
+  locking is not done.  This is most likely due to calling a wrapper function
+  that follows a sequence like this:
+
+  - Python -> wrapper function
+  - wrapper function -> C GStreamer function
+  - C GStreamer function -> side effect code
+  - side effect code -> callback
+  - callback -> tries to acquire Python GIL but it's already locked
+  - deadlocked...
+
+  This has been fixed for commonly called functions that have side effects
+  which are likely to re-enter the interpreter.  It just involves lock/unlock
+  around the call to the C gst function.  But doing it for every function could
+  have performance issues and, more importantly, is not an automated process.
+
+  Please file a bug_ if you have problems related to this and need other
+  functions to be specially handled.
+
+* Gdk lock
+
+  If you are using PyGTK you will have to deal with Gdk locking.  Make sure
+  you're holding the Gdk lock while executing Gdk/Gtk calls.  See PyGTK
+  documentation and FAQ list for more information.
+
+
+Pipeline Iteration
+------------------
+
+There are a number of ways to iterate pipelines.  ./examples/gstreamer/bps.py
+is a small test program to measure the performance in buffers per second of
+these various techniques.  Please see the example for how to use these
+techniques.
+
+* Bin.iterate() in Python from the gtk idle loop
+* gst_bin_iterate() in C from gtk idle loop
+* Bin.iterate() in a Python loop
+* gst_bin_iterate() in a C loop
+
+The method you chose depends on your application.  The idle loop methods are
+slightly slower yet more flexible.  Probably useful for interactive GUI
+applications.
+
+The basic loop methods are faster but probably more use for non-interactive
+applications.  A variation on these loops would be to also check for a stop
+condition which may provide performance increase and some level of control.
+
+
+Python Elements
+---------------
+
+It is possible to write Python subclasses of GstElement.  This support is very
+primitive and likely to change.  See "``./examples/gstreamer/rot13.py``" for an
+example.
+
+
+Bugs
+====
+
+*Please* submit gst-python bugs, patches, or suggestions to GNOME Bugzilla_,
+Product: GStreamer, Component: gst-python.  Thank you.
+
+.. _Bugzilla: http://bugzilla.gnome.org/
+.. _bug: `Bugs`_

TODO

@@ -1,17 +1,27 @@
-gst-python TODO
+.. gst-python TODO
-===============
+.. This file writen with docutils markup (http://docutils.sourceforge.net/)
+
+TODO
+====
 
 - handle more of the functions that need manual wrapping code
 - add check that pygtk built with --enable-thread
 - improve Python gstreamer.Element creation
-  - perhaps make drop _set_foo_function() calls in favor of object methods
+
+  - perhaps drop _set_foo_function() calls in favor of object methods
   - sane buffer handling with buffer type or Numeric?
+
 - docs
+
   - API ref
   - manual
   - tutorial
+
 - more examples
 - convert build system to distutils
 - wrap other GStreamer helper libs
 - add some standard widgets
+
   - gtk video widget (similar to widget gst-player is using)
+
+- testsuite

docs/HEAD.in

@@ -0,0 +1,13 @@
+.. gst-python HEAD.in
+.. This file writen with docutils markup (http://docutils.sourceforge.net/)
+
+==========
+gst-python
+==========
+
+:Author: David I. Lehn
+:Contact: dlehn@users.sourceforge.net
+:Web site: http://www.gstreamer.net/bindings/python/
+:Version: @VERSION@
+
+.. contents::

docs/Makefile.am

@@ -0,0 +1,27 @@
+EXTRA_DIST = HEAD.in docutils.conf gst-python.css
+
+DOCS = \
+	$(srcdir)/HEAD \
+	$(top_srcdir)/NEWS \
+	$(top_srcdir)/README \
+	$(top_srcdir)/TODO \
+	$(top_srcdir)/AUTHORS
+
+gst-python.html: docutils.conf ${DOCS}
+	@if [ ! $$DOCUTILSHOME ]; then \
+		echo "ERROR: Please set \$$DOCUTILSHOME"; \
+		exit 1; \
+	fi
+	@if [ ! -r $$DOCUTILSHOME/tools/html.py ]; then \
+		echo "\$$DOCUTILSHOME/tools/html.py not found"; \
+		exit 1; \
+	fi
+	rm -f gst-python.txt
+	for doc in ${DOCS}; do \
+		cat $$doc >> gst-python.txt; \
+		printf "\n" >> gst-python.txt; \
+	done
+	PYTHONPATH=$$PYTHONPATH:$$DOCUTILSHOME $$DOCUTILSHOME/tools/html.py gst-python.txt gst-python.html
+	lynx -dump -force_html gst-python.html > gst-python.out
+
+CLEANFILES = gst-python.txt gst-python.html

docs/docutils.conf

@@ -0,0 +1,9 @@
+[options]
+
+# These entries affect all processing:
+source-link: 1
+datestamp: %Y-%m-%d %H:%M UTC
+generator: 1
+
+# These entries affect HTML output:
+stylesheet-path: gst-python.css

docs/gst-python.css

@@ -0,0 +1,191 @@
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+
+.first {
+  margin-top: 0 }
+
+.last {
+  margin-bottom: 0 }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+dd {
+  margin-bottom: 0.5em }
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em }
+
+div.footer, div.header {
+  font-size: smaller }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr {
+  width: 75% }
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font-family: serif ;
+  font-size: 100% }
+
+pre.line-block {
+  font-family: serif ;
+  font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+  margin-left: 2em ;
+  margin-right: 2em ;
+  background-color: #eeeeee }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.option-argument {
+  font-style: italic }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+table {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.citation {
+  border-left: solid thin gray ;
+  padding-left: 0.5ex }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.footnote {
+  border-left: solid thin black ;
+  padding-left: 0.5ex }
+
+td, th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+th.docinfo-name, th.field-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+  font-size: 100% }
+
+tt {
+  background-color: #eeeeee }
+
+ul.auto-toc {
+  list-style-type: none }