Tuesday, February 1, 2011

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!

5 comments:

  1. before last release of gnome g-i gave devs a hard time to release their libs with right introspection support. Now you want them to give a hard time porting docs.

    What is the profit of this move if its not a secret?

    ReplyDelete
  2. @alex-butenko: I'm not telling anyone to do anything. I'm just giving pointers to those that have interest on this work.

    ReplyDelete
  3. Its pretty much Done already,
    Introspection doc generator in git.gnome.org does all the hard work, tweaking it to generate python or gjs should be quite trivial.

    Code is quite clean, if any one wants to commit changes, feel free to do so.

    The output is generated twice weekly here, roojs.com/seed

    ReplyDelete
  4. Oops, my mistake, i reread it and realized you are talking about the C Api docbook generated from girs

    ReplyDelete
  5. Alan: that code is unfortunately written in the wrong language. To be able to be used as a gtk-doc replacement it would have to be written in something that gtk+ etc can depend on.

    ReplyDelete