[glade3] * doc/gladepython.sgml: added Glade Python plugin documentation.

[Juan Pablo Ugarte <jpu src gnome org>]

commit 1ca1df8f078caaa18967701300943bca91f73f46
Author: Juan Pablo Ugarte <jp synctv com>
Date:   Tue Apr 21 22:09:40 2009 -0300

    * doc/gladepython.sgml: added Glade Python plugin documentation.
    
    * doc/gladeui-docs.sgml, doc/Makefile.am: added reference to the new docs.
---
 ChangeLog             |    6 +++
 doc/Makefile.am       |    6 ++-
 doc/gladepython.sgml  |   82 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/gladeui-docs.sgml |    2 +
 4 files changed, 94 insertions(+), 2 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index fe053b0..b38b8cd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2009-04-21  Juan Pablo Ugarte <juanpablougarte gmail com>
+
+	* doc/gladepython.sgml: added Glade Python plugin documentation.
+	
+	* doc/gladeui-docs.sgml, doc/Makefile.am: added reference to the new docs.
+
 2009-04-18  Tristan Van Berkom <tvb gnome org>
 
 	* plugins/gtk+/gtk+.xml.in: Fixed GtkButton to only allow real stock items,
diff --git a/doc/Makefile.am b/doc/Makefile.am
index f04d84f..e33714b 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -76,7 +76,8 @@ content_files=\
 	version.xml \
 	catalogintro.sgml \
 	widgetclasses.sgml \
-	properties.sgml
+	properties.sgml \
+	gladepython.sgml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
@@ -84,7 +85,8 @@ content_files=\
 expand_content_files=\
 	catalogintro.sgml \
 	widgetclasses.sgml \
-	properties.sgml
+	properties.sgml \
+	gladepython.sgml
 
 # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
 # Only needed if you are using gtkdoc-scangobj to dynamically query widget
diff --git a/doc/gladepython.sgml b/doc/gladepython.sgml
new file mode 100644
index 0000000..3620148
--- /dev/null
+++ b/doc/gladepython.sgml
@@ -0,0 +1,82 @@
+<refentry id="pythonsupport" revision="7 Nov 2008">
+ <refmeta>
+   <refentrytitle>Python Gtk widgets support</refentrytitle>
+   <refmiscinfo>Glade UI</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+   <refname>Add python support to your catalog</refname>
+   <refpurpose>
+How to write and install a catalog for a python widget library
+   </refpurpose>
+ </refnamediv>
+
+ <refsect1>
+   <title>Introduction</title>
+Glade supports loading widgets coded in python by linking and running the python
+interpreter from the gladepython catalog plugin.
+   <para>
+
+   </para>
+
+   <para>
+So in order for glade to include your python gtk widgets you will have to:
+
+<varlistentry><listitem>
+a) specify gladepython support code as your plugin library.
+</listitem></varlistentry>
+
+<varlistentry><listitem>
+b) set glade_python_init as you init function.
+</listitem></varlistentry>
+
+<varlistentry><listitem>
+c) make sure your catalog name is the same as your python import library since
+glade_python_init() will use this name to import your widgets into the
+interpreter.
+</listitem></varlistentry>
+
+     <programlisting>
+<![CDATA[
+<glade-catalog name="pythonplugin" library="gladepython"
+domain="glade-3" depends="gtk+">
+ <init-function>glade_python_init</init-function>
+
+ <glade-widget-classes>
+   <glade-widget-class title="MyBox" name="MyBox" generic-name="mybox"/>
+ </glade-widget-classes>
+
+ <glade-widget-group name="python" title="Python">
+   <glade-widget-class-ref name="MyBox"/>
+ </glade-widget-group>
+</glade-catalog>]]>
+     </programlisting>
+   </para>
+
+   <para>
+Glade's python interpreter will look up for your widgets in the same
+places it looks
+for regular catalogs plugins, that is $GLADE_ENV_CATALOG_PATH
+enviroment variable
+and `pkg-config --variable=catalogdir gladeui-1.0`
+
+So the easiest thing would be to make a symlink in one of those directory, just
+do not forget that the name should be the one specified in your catalog name.
+   </para>
+
+   <para>
+pythonplugin.py
+     <programlisting>
+<![CDATA[
+import gobject
+import gtk
+
+class MyBox(gtk.HBox):
+       __gtype_name__ = 'MyBox'
+
+       def __init__(self):
+               gtk.HBox.__init__(self)
+</glade-catalog>]]>
+     </programlisting>
+   </para>
+ </refsect1>
+</refentry>
diff --git a/doc/gladeui-docs.sgml b/doc/gladeui-docs.sgml
index 42116a1..4716fc1 100644
--- a/doc/gladeui-docs.sgml
+++ b/doc/gladeui-docs.sgml
@@ -4,6 +4,7 @@
 <!ENTITY CatalogIntro SYSTEM "xml/catalogintro.sgml">
 <!ENTITY WidgetClasses SYSTEM "xml/widgetclasses.sgml">
 <!ENTITY Properties SYSTEM "xml/properties.sgml">
+<!ENTITY PythonSupport SYSTEM "xml/gladepython.sgml">
 <!ENTITY GladeCommand SYSTEM "xml/glade-command.xml">
 <!ENTITY GladeApp SYSTEM "xml/glade-app.xml">
 <!ENTITY GladeClipboardView SYSTEM "xml/glade-clipboard-view.xml">
@@ -56,6 +57,7 @@ custom GTK+ derived widgets into the Glade UI Designer.
     &CatalogIntro;
     &WidgetClasses;
     &Properties;
+	&PythonSupport;
   </part>
 
   <part id="core">