On 03/04/2014 04:18 PM, Giovanni Campagna wrote: > 2014-02-27 16:53 GMT+01:00 Stefan Sauer <[email protected]>: >> On 02/26/2014 08:27 PM, Giovanni Campagna wrote: >> >> Hello desktop developers, >> >> as some of you may have noticed, there has been some activity on the >> documentation generator for gobject-introspection, and in particular a >> lot of improvements on the Gjs side. >> Now the result are beginning to appear, and you can see them here: >> https://people.gnome.org/~gcampagna/docs/ >> >> In particular, what is interesting is that we blend in generated and >> manually edited documentation. This allows us to remove all of GLib >> and GObject that is not interesting or badly annotated, and it lets us >> add things like GObject.Class ( >> https://people.gnome.org/~gcampagna/docs/GObject-2.0/GObject.Class.html >> ), which is the gjs specific way to define new GTypes. >> I hope to finish with the other overrides soon (the biggest ones are >> GLib.Variant and Gio.DBus*, but there's some minor stuff), which >> should solve one of the greatest hurdles in taking up gjs programming. >> The sources for this generation are not hosted anywhere, because I >> don't know if it makes sense to store generated (or semi-generated) >> files in git. I think it does, at least for GLib and GObject, because >> the update is always manual. cairo has the same problem, because we >> bind it manually, and the "native" gjs modules need documentation too. >> >> Of course, this location is only temporary, and I hope we will move to >> library-web at some point. This would also fix the styling, which >> right now is "poor" (it's a pure yelp-build of the mallard docs). >> The interesting part, though, is that the documentation, at least for >> the schematic parts, is correct and existing. >> >> >> awesome! A few comments/questions: >> >> 1) are there plans to get this into devhelp? We need to figure a namespace >> scheme for binding docs. The devhelp app itself already understands >> different languages. All we need is a index file like the ones gtk-doc >> generates. > No, there are no plans to get this in devhelp. The HTML output is > really just a way to get them somewhere in the internet without > blocking on library-web, but the real deliverable is mallard, and > devhelp does not understand that (while library-web does) I'll try installing a xml file with referenced stylesheet + index.sgml to see if on-the-fly transformations work in devhelp. My main concern are the id attributes that we need for the local anchors.
Is it a conscious decision to make have them not in devhelp, or more a matter of someone figuring out how to make them show up there? Stefan > >> 2) I think it would be nice to share the css with gtk-doc so that the >> various docs are closer to each other. >> >> 3) there seem to be empty Returns: tags in the docs - e.g. >> https://people.gnome.org/~gcampagna/docs/Gst-1.0/Gst.Pipeline.get_bus.html > Fixed now. > >> 4) having these " // Gjs wrapper for gst_pipeline_get_bus()" comment in the >> method synopsis looks weird. > That comment was Jasper's idea, my idea was "[native code for ...]" > (similar to what JS uses for native code functions already). > The comment syntax has the advantage of being valid JS - which is also > a disadvantage, in a way, because if you try to run that code nothing > happens... > >> Again thanks for doing this. I look forward to see a quick write out how the >> docs are generated. > You can see the Makefile in gjs-documentation for now, it's fairly simple. > > Giovanni _______________________________________________ desktop-devel-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/desktop-devel-list
