GNOME Development Network: An attempt to improve the GNOME developer experience

I thought it'll be nice to blog about this before the Documentation Hackfest was started.

I am quite frustrated with the current situation with regards the API reference browsing experience in the GObject world, some of the problems are these:

  • I can't quickly get a compact overview of all the properties, methods and signals of a given class
  • On top of that, I need to open each super-class or interface page separately to know which properties are inherited from those
  • I can't figure out all functions/methods use a given class as an argument or return type, or which classes use it as a property.
  • People can't add comments or code samples to each struct/class/method/…
  • People can't easily suggest amendments to the documentation without diving into the code and generating a patch + a bug in bugzilla.

On top of that, usability wise I'm not too happy with the current web frontend and/or devhelp. The information to figure out all these things are all in GIR files, so I gave it a thought and figured out what's needed. Turns out we are not too far.

So I've been developing GDN (GNOME Development Network) a little django app hosted in github using kamstrup's giraffe.  which takes GIR files and dumps them into static HTML code. The GIR parsing stuff is quite clever and useful, but we need a dynamic app if we want to provide some of the most interesting features, so I'm ussing giraffe's AST to dump all the cross referenced information into an SQL database.

So far I've managed to dump most info, the Django data model is pretty much done, I need to fix some bugs with regards to resolving specific types while crawling the parameters and return.

You need to install my personal giraffe's branch for now until Mikkel comes back from vacation and if you want it to work as I've been adding some missing features to the AST code.

So far I only have backend code no frontend code at all. Stay tuned for more info on this, and if anyone is willing to help make sure you send me an email to aruiz at gnome dot org

6 thoughts on “GNOME Development Network: An attempt to improve the GNOME developer experience

  1. This sounds good, especially if you could generate the docs so that they make sense for a particular programming language. See for example the generated GIR docs for gjs:
    Another useful thing would be to generate the docs locally so the developer would have documentation for the all GIR interfaces that he has installed. This would be good for projects like Midgard where we provide a GIR API but are not usually part of GNOME.


  2. I have been pondering if gtk-doc should include a collapsible list of inherited signals and properties. This would work inside a library. If a class is subclassing a class from a different library, then the list of signals and properties would be that of the docuemntation build time (if the other library adds a property it would only show up when updating the docs). Probably still worth doing it.
    The more complicated solution would be to use javascript to fetch the inherited members when showing the page.


  3. I really like the initiatve. I’ve always liked the ‘annotated manual’ that PHP has, where users add examples, ask questions on things where the reference is not 100% clear, and others answer those questions.
    Often I immediately scrolled down to the user comments to look for examples instead of reading the reference 😉


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s