PyGObject GTK+ 3 - Documentation?

I agree that this is a huge shortcoming of the PyGObject in it's current state. For those of us who have been using GTK+ for a while it's no problem, but, for new users it can be confusing.

Folks are working on a system to automatically generate the docs for languages other than C which is known as GObject Introspection Doctools. Since that's not quite ready yet, your best bet to use the C API documentation and learn how it translates to Python. It's not as hard as it sounds.

Remember, the Python calls are dynamically wrapped to the underlying C library. All you need to do is learn how a few things are typically translated to Python and understand how GTK+ "properties" work. It's basically a naming convention in C and the patterns are easy to learn. The PyGObject/Introspection Porting page is a good start.

A constructor in Python is generally wrapped to the *_new() function in C. PyGObject also allows you to pass in any GTK+ property belonging to that widget as keyword arguments in the constructor. Thus, you have a lot of options when constructing widgets in Python.

You had mentioned the GtkWindow. If you look at the GtkWindow Documentation, the gtk_window_new() function takes a window type as an argument in C. This would be a positional argument to the constructor in Python. PyGObject "overrides" the constructor so that the type is optional and defaults to a top-level window. There are a bunch of GtkWindow properties that could also be passed to the constructor as keyword arguments.

Here are 3 examples of constructing a Gtk.Window in Python which are functionally equivelent:

# this is very close to how it's done in C using get_*/set_* accessors.window = Gtk.Window(Gtk.WindowType.TOPLEVEL)window.set_title("Hello")# setting properties as keyword arguments to the constructorwindow = Gtk.Window(type=Gtk.WindowType.TOPLEVEL, title="Hello")# set_properties() can be used to set properties after constructionwindow = Gtk.Window()window.set_properties(title="Hello")

The Python interactive console can be a great way to experiment with widgets and properties.

The docs are located here: https://lazka.github.io/pgi-docs/Gtk-3.0/index.html

The Gtk.Window arguments (exactly what you have asked for) here:https://lazka.github.io/pgi-docs/Gtk-3.0/classes/Window.html

Some interactive console solutions exist above, but I prefer the auto-complete one:How do I add tab completion to the Python shell?

To expand a little to the accepted answer; the GObject Introspection Doctools page has a section on how to create your own documentation.

On Ubuntu 12.04.2 LTS you can issue the following commands:

$> g-ir-doc-tool --language Python -o ./output_dir /usr/share/gir-1.0/Gtk-3.0.gir$> yelp ./output_dir/index.page