Last week I spent a few days at the Developer Experience hackfest and got to have some fun again with the API reference generator in gobject-introspection.
Jon intended to hack on the XSLT stylesheets in yelp-tools/xsl, but after some trying he got discouraged by the amount of work that would take to get them to generate the HTML that we are interested in. We also discussed the benefits of using Mallard for generating the reference docs, and given that we want to generate a single output, we couldn't see much value in the level of indirection that Mallard adds.
Thus, we considered generating HTML directly from the GIR files, but shortly after Alberto Ruiz came by and offered to explore a client-side-only solution involving processing JSON files with JavaScript.
He very quickly got something relatively complete, which is very encouraging, but even more so is seeing how other projects are generating their API references that way, for example: http://docs.sencha.com/extjs/4.2.2/#!/api/Ext.Class
Aspects such as as-you-type search would bring the online documentation on par with the Devhelp experience. Plus they have some niceties such as a symbol browser and links to annotated source code.
I have hacked a (yet another) --write-json-files switch to g-ir-doc-tool that will output the content of the GIR file to JSON, but indexed and formatted as needed by the JS side of things. See this branch for the code.
That branch also adds support for Markdown rendering using python-markdown, but some more code needs to be written to implement the extensions to Markdown that the Gtk+ docs are using.
It was great to talk about all this and more with old and new friends in Berlin, so I'm very grateful to the GNOME Foundation for organizing it and sponsoring travel, and to Endocode for providing a venue. And special thanks to Chris Kühl for the great organization!
Jon intended to hack on the XSLT stylesheets in yelp-tools/xsl, but after some trying he got discouraged by the amount of work that would take to get them to generate the HTML that we are interested in. We also discussed the benefits of using Mallard for generating the reference docs, and given that we want to generate a single output, we couldn't see much value in the level of indirection that Mallard adds.
Thus, we considered generating HTML directly from the GIR files, but shortly after Alberto Ruiz came by and offered to explore a client-side-only solution involving processing JSON files with JavaScript.
He very quickly got something relatively complete, which is very encouraging, but even more so is seeing how other projects are generating their API references that way, for example: http://docs.sencha.com/extjs/4.2.2/#!/api/Ext.Class
Aspects such as as-you-type search would bring the online documentation on par with the Devhelp experience. Plus they have some niceties such as a symbol browser and links to annotated source code.
I have hacked a (yet another) --write-json-files switch to g-ir-doc-tool that will output the content of the GIR file to JSON, but indexed and formatted as needed by the JS side of things. See this branch for the code.
That branch also adds support for Markdown rendering using python-markdown, but some more code needs to be written to implement the extensions to Markdown that the Gtk+ docs are using.
It was great to talk about all this and more with old and new friends in Berlin, so I'm very grateful to the GNOME Foundation for organizing it and sponsoring travel, and to Endocode for providing a venue. And special thanks to Chris Kühl for the great organization!
