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.
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!
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 |
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!
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.
ReplyDeleteWhat is the profit of this move if its not a secret?
@alex-butenko: I'm not telling anyone to do anything. I'm just giving pointers to those that have interest on this work.
ReplyDeleteIts pretty much Done already,
ReplyDeleteIntrospection 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
Oops, my mistake, i reread it and realized you are talking about the C Api docbook generated from girs
ReplyDeleteAlan: 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