From bb16c7387501479a042b0927d6f881afd1019259 Mon Sep 17 00:00:00 2001 From: "David I. Lehn" Date: Thu, 26 Jun 2003 08:48:52 +0000 Subject: [PATCH] kill docutils based docs (easy come, easy go) docbook based docs Original commit message from CVS: kill docutils based docs (easy come, easy go) docbook based docs --- AUTHORS | 40 +---- ChangeLog | 10 ++ NEWS | 11 +- README | 187 +--------------------- TODO | 28 +--- configure.ac | 1 - docs/.gitignore | 3 + docs/HEAD.in | 13 -- docs/Makefile.am | 42 +++-- docs/common.xsl | 7 + docs/docutils.conf | 9 -- docs/gst-python.css | 191 ----------------------- docs/gst-python.xml | 435 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/html.xsl | 8 + docs/pdf.xsl | 18 +++ 15 files changed, 503 insertions(+), 500 deletions(-) create mode 100644 docs/.gitignore delete mode 100644 docs/HEAD.in create mode 100644 docs/common.xsl delete mode 100644 docs/docutils.conf create mode 100644 docs/gst-python.xml create mode 100644 docs/html.xsl create mode 100644 docs/pdf.xsl diff --git a/AUTHORS b/AUTHORS index df15ca4..f42d485 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,39 +1 @@ -.. gst-python AUTHORS -.. This file writen with docutils markup (http://docutils.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 - -Contributions -------------- - -Patches, suggestions, and other help: - -* Kenichi Sato ) - -Much of the framework for gst-python stolen from gtk and gconf bindings by: - -* James Henstridge -* Johan Dahlin -* Matt Wilson -* and many more... - -GStreamer ---------- - -And of course, none of this would be possible without the extreme hacker mojo -of the whole GStreamer crew! +The gst-python AUTHORS list is maintained at docs/gst-python.xml#authors. diff --git a/ChangeLog b/ChangeLog index 53c44f3..4a83fdc 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2003-06-26 David I. Lehn + + * configure.ac, AUTHORS, NEWS, README, TODO, docs/Makefile.am, + docs/HEAD.in docs/docutils.conf, docs/gst-python.css: + kill docutils based docs (easy come, easy go) + + * AUTHORS, NEWS, README, TODO, docs/Makefile.am, docs/gst-python.xml, + docs/common.xsl, docs/html.xsl, docs/pdf.xsl, docs/gst-python.css: + docbook based docs + 2003-06-25 David I. Lehn * gstreamer/Makefile.am: fix up line continuations diff --git a/NEWS b/NEWS index 531887d..8d0b980 100644 --- a/NEWS +++ b/NEWS @@ -1,10 +1 @@ -.. gst-python NEWS -.. This file writen with docutils markup (http://docutils.sourceforge.net/) - -News -==== - -2003-06-xx - 0.1.0 released ---------------------------- - -* first release +The gst-python NEWS is maintained at docs/gst-python.xml#news. diff --git a/README b/README index f18f192..81edc5f 100644 --- a/README +++ b/README @@ -1,186 +1 @@ -.. gst-python README -.. This file writen with docutils markup (http://docutils.sourceforge.net/) - -About -===== - -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. - -.. _Python: http://www.python.org/ -.. _GStreamer: http://www.gstreamer.net/ - - -Requirements -============ - -* Python_ 2.2 -* GStreamer_ 0.6.0 -* PyGTK_ 1.99.14 - -.. _PyGTK: http://www.daa.com.au/~james/pygtk/ - - -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:: - - $ export PYTHONPATH=$PYTHONPATH:`pwd` - -Try running examples:: - - $ cd examples/gstreamer/ - $ python cp.py - $ cmp - $ python vorbisplay.py - - -Documentation -============= - -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`_ +The gst-python README is maintained in doc/gst-python.xml. diff --git a/TODO b/TODO index 88c4d32..8b6f2d1 100644 --- a/TODO +++ b/TODO @@ -1,27 +1 @@ -.. 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 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 +The gst-python TODO list is maintained at docs/gst-python.xml#todo. diff --git a/configure.ac b/configure.ac index e1cb7fb..d8bc0bb 100644 --- a/configure.ac +++ b/configure.ac @@ -119,6 +119,5 @@ AC_OUTPUT([ examples/Makefile examples/gstreamer/Makefile docs/Makefile - docs/HEAD gst-python.spec ]) diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..4c1e751 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +gst-python.html +gst-python.txt +gst-python.pdf diff --git a/docs/HEAD.in b/docs/HEAD.in deleted file mode 100644 index fb780c8..0000000 --- a/docs/HEAD.in +++ /dev/null @@ -1,13 +0,0 @@ -.. 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:: diff --git a/docs/Makefile.am b/docs/Makefile.am index da04cda..c0d9007 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,27 +1,21 @@ -EXTRA_DIST = HEAD.in docutils.conf gst-python.css +XMLFILES = gst-python.xml +XSLFILES = common.xsl html.xsl +CSSFILES = gst-python.css -DOCS = \ - $(srcdir)/HEAD \ - $(top_srcdir)/NEWS \ - $(top_srcdir)/README \ - $(top_srcdir)/TODO \ - $(top_srcdir)/AUTHORS +DOCS = gst-python.txt gst-python.html -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 +all: $(DOCS) -CLEANFILES = gst-python.txt gst-python.html +gst-python.txt: gst-python.xml + xmlto txt $< +# cp gst-python.txt $(top_builddir)/../README + +gst-python.html: gst-python.xml common.xsl html.xsl + xmlto -m common.xsl -m html.xsl xhtml-nochunks $< + +gst-python.pdf: gst-python.xml common.xsl pdf.xsl + xmlto -m common.xsl -m pdf.xsl pdf $< + +CLEANFILES = $(DOCS) + +EXTRA_DIST = $(XMLFILES) $(XSLFILES) $(CSSFILES) diff --git a/docs/common.xsl b/docs/common.xsl new file mode 100644 index 0000000..8495981 --- /dev/null +++ b/docs/common.xsl @@ -0,0 +1,7 @@ + + + + + + diff --git a/docs/docutils.conf b/docs/docutils.conf deleted file mode 100644 index 2f455f9..0000000 --- a/docs/docutils.conf +++ /dev/null @@ -1,9 +0,0 @@ -[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 diff --git a/docs/gst-python.css b/docs/gst-python.css index fe8dc8e..e69de29 100644 --- a/docs/gst-python.css +++ b/docs/gst-python.css @@ -1,191 +0,0 @@ -/* -: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 } diff --git a/docs/gst-python.xml b/docs/gst-python.xml new file mode 100644 index 0000000..077a127 --- /dev/null +++ b/docs/gst-python.xml @@ -0,0 +1,435 @@ + + + +
+ + The GStreamer Development Team + June ??, 2003 + 2003David I. Lehn + <application>gst-python</application>: A Python Interface to GStreamer + gst-python + + + David + I. + Lehn + dlehn@users.sourceforge.net + + + + Introductory information for the GStreamer Python bindings. + + + + + 0.1.0 + 2003-06-?? + dil + Initial version. + + + + + + +
+About + + +gst-python: the Python bindings for the GStreamer project. These bindings provide access to almost all of the GStreamer C API through an object oriented Python API. + + +
+ + + +
+News + + + + + + + + + Date + Version + Notes + + + + + 2003-06-xx + 0.1.0 + first release + + + + + +
+ + + +
+Installation + + + +
+Requirements + + +Python 2.2 () + + +GStreamer 0.6.x (except 0.6.1) () + + +PyGTK 1.99.14 () + + +
+ + + +
+Building and Installation + + +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: + + + + + $ export PYTHONPATH=$PYTHONPATH:`pwd` + + + + +Try running examples: + + + + + $ cd examples/gstreamer/ + $ python cp.py <input file> <output file> + $ cmp <input file> <output file> + $ python vorbisplay.py <an Ogg Vorbis file> + + + +
+ + + +
+ + + +
+Programming + + + +
+General API + + +The gst-python bindings are directly generated from the GStreamer headers. Look at the GStreamer documentation at for general API and programming issues. In most cases the GStreamer classes and boxed types map directly to Python classes. The function-based GObject methods also map onto Python methods. + + +
+ + + +
+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 . 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 currently 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 are 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 calls wrapper function +wrapper function calls C GStreamer function +C GStreamer function calls side effect code +side effect code calls 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. Or alternatively send a message to the gstreamer-devel list or the maintainer. Thank you. + +
+ + + +
+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 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 + +
+ + + +
+Authors + + +Please feel free to contact the developers. They hang out on IRC () and the mailing lists (). + + + + +
+Maintainer + + +David I. Lehn dlehn at users.sourceforge.net + +
+ + + +
+Contributions + +Patches, suggestions, and other help: + + + +Kenichi Sato ksato at users.sourceforge.net + + + +Much of the framework for gst-python stolen from gtk and gconf bindings by: + + + +James Henstridge james at daa.com.au +Johan Dahlin jdahlin at telia.com +Matt Wilson msw at redhat.com +and many more... + + +
+ + + +
+GStreamer Team + +And of course, none of this would be possible without the extreme hacker mojo +of the whole GStreamer crew! + +
+ + + +
+ + + +
diff --git a/docs/html.xsl b/docs/html.xsl new file mode 100644 index 0000000..ff36dd4 --- /dev/null +++ b/docs/html.xsl @@ -0,0 +1,8 @@ + + + + + + + diff --git a/docs/pdf.xsl b/docs/pdf.xsl new file mode 100644 index 0000000..9f0bcc8 --- /dev/null +++ b/docs/pdf.xsl @@ -0,0 +1,18 @@ + + + +0.5in + + + + 1 + + + -- 2.7.4