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

Generating API docs from .gir files

From time to time people ask which are the plans about generating API documentation from the introspected information in the .gir files that g-ir-scanner outputs.

More often, I hear someone swearing about how hard is to setup gtk-doc to correctly generate documentation for your code. And getting g-ir-scanner to generate .gir files as expected is not completely trivial either.

It should be apparent that generating the docs from the .gir would save quite a bit of grief altogether but for one reason or another this hasn't happened yet. Docstrings are in the .gir files already along with the rest of the metadata but gtk-doc is still scanning the C sources.

© Juan José Sánchez Penas

During last GUADEC, the gobject-introspection people could be seen hacking in the lobby instead of attending your talk or rioting against the release team, and one of the outcomes was Zach Goldberg's g-ir-docgen script. His new employer forbids doesn't sponsor him for this work so this has been in the freezer since then.

So we can eventually get out from this situation, I would like to encourage interested non-coding people to add to CC on this bug: https://bugzilla.gnome.org/show_bug.cgi?id=625494

And to those that can actually code, please consider using that ticket to coordinate the effort, it may take less work than you think and it can be a fun hack. Think of all the GNOME hackers that will thank you!