Progress on generating Python API docs from introspection

The Docs hackfest in Brno is nearing to an end and I think enough progress has happened on generating API reference from introspection to warrant a report.

To see the current state, check the Telepathy-GLib reference generated here for Python.

Tomorrow morning will work on fixing some issues in the GIR files such as enum docs not making to it and then I will head home.

I'm not likely to work further on this, so if you think it can be of use to you, please consider lending a hand and contribute bugfixes and features. And if you don't like the design or the layout, just change it :)

Hope you have as much fun with this as I have had!

Once more, thanks to the GNOME Foundation, Red Hat and Collabora for sponsoring this work.

Below you can get a glance of what has been progressed on during these days, here is the changelog:

• Add some more stuff to Enum pages
• Display the hierarchy tree for classes
• Install the Mako template files
• Add AM_CHECK_PYMOD macro and use it to check for Mako
• Remove stale DocBook files
• Properly link to property pages
• Fix names of xref links
• Move constructor example to follow the class doc body
• Properly link to signal pages
• Fix the id of signal pages for Python
• Qualify the class name in the constructor with the module name
• Add links to properties in the constructor
• Fix link
• Show how to construct instances in the Class page
• Add details for properties in Python
• Add param information to signal pages in Python
• Implement intra-namespace cross references
• Use instances of MallardFormatter* instead of class methods
• Remove some occurrences of empty Returns: lines
• use True and False instead of %TRUE and %FALSE
• Remove module and class from the function signature
• Use template caching
• Use None instead of %NULL
• Use the ctype for the return type in signatures
• Display Returns: even if there's no args
• Update expected, some whitespace was removed
• Add Since: tag to classes
• Add Since: tag to mallard docs
• Add function argument docs to the C template
• Add argument docs to the Python template
• Don't instantiate MallardFormatter for unknown languages
• Update expected mallard for the doc tests

Docs hackfest: starting point

Have spent my trip to Brno undusting and rebasing the branch in gobject-introspection that uses to Mako templates to generate Mallard code from GIR files.

Here you can see how looks like the generated documentation for the Account class in the TelepathyGLib typelib for Python, and here is the one generated with gtk-doc.

As can be seen, there's still a long way to get even close to the gtk-doc level, but it's a very promising start.

Documentation hackfest in Brno 2012

Tomorrow I'm taking the train to Brno to participate in the documentation hackfest, with plans to continue the work on generating API documentation from the GIR files that are generated by GObject Introspection.

I will be continuing the work that a bunch of us started in Berlin during the GObject Introspection hackfest last year.

Will be giving as well a workshop on GNOME application development with Python and GObject Introspection as part of the Developer Conference 2012 that Red Hat is organizing there.

Thanks to the GNOME Foundation for sponsoring my accommodation, to my employer Collabora for sponsoring my time there and Red Hat for sponsoring the venue and the food.

PyGObject gets a splash of new blood

Things as they are, few hackers get to work on the same project their whole life. No matter how deep one has been involved in a project, and how much effort was put in, there are many reasons why at some point one may decide to distance from it.

For different reasons, the people who have been maintaining PyGObject for the last couple of years (since the move to introspection) aren't currently using it much any more, which isn't ideal because it means they can allocate less time to maintenance and also lack the guidance of their own motivation.

Fortunately for PyGObject, a bunch of heroic hackers have stepped forward to take the responsibility of maintaining it:

• Martin Pitt
• Paolo Borelli
• Ignacio Casal Quintero
• Sebastian Pölsterl

For now I remain listed in the .doap file, but as I'm not using PyGObject myself any more (even though Collabora sponsors some of my time working on PyGObject), my involvement will be limited to occasional patches and code reviews as I find time.

My thanks and admiration to those who have maintained PyGObject in the past:

• Johan Dahlin
• James Henstridge
• John (J5) Palmieri
• Simon van der Linden
• Zach Goldberg
• Gustavo J Carneiro
• Paul Pogonyshev
• Gian Mario Tagliaretti

To end, just note that Martin is using his canonical.com address, so I assume that Canonical is sponsoring his work as maintainer upstream, so kudos to them as well.