Re: API documentation from introspection data

[Tomeu Vizoso <tomeu tomeuvizoso net>]

On Fri, Jan 27, 2012 at 16:33, Alberto Ruiz <aruiz gnome org> wrote:
>
>
> 2012/1/27 Alberto Ruiz <aruiz gnome org>
>>
>> Hello guys,
>>
>> Just for the record, I've started coding a small django app in github to
>> see how far can I get with regards a richer API reference web interface.
>> I'm reusing Mikkael Kampstrup's giraffe[1] AST code for GIR and I'm
>> translating that to a django data model (SQL) structure.
>>
>> There are two features missing from both devhelp and the current online
>> API reference that I'm interested in achieving:
>> - Figuring out properties/methods/signals from parent classes or
>> interfaces inline (collapsed initially)
>> - Figuring out which methods/signals use a given type as argument, or
>> which classes/interfaces as properties
>>
>> I think that a dynamic approach is much more interesting than the current
>> statically generated one. And quite frankly, as it stands right now, it's
>> not
>>
>
> Clicked Sent by accident.
>
> I was going to say I'm not too far from getting the whole thing to a decent
> state, though I will need help to make the frontend pretty.
>
> Further down the line, I also want to provide amendments to the
> documentation and have a contribution queue. And I also want to allow
> comments for people to submit code examples.

Hi Alberto,

first of all, sorry for the absurdly late reply, have just read your
blog post on the subject [0] and that reminded me that I had this
email waiting.

There seems to be a lot of overlap between these two approaches so I'm
going to explain our justifications in the hope that we can pool
resources in some way. The main diverging points are IMO Mallard, the
GIR parser and the medium-term goals.

We started generating DocBook from GIR files, trying to mimic GTK-Doc
as much as possible. Progress was slow and we had quite some problems
trying to rescue the DocBook that is embedded in the C sources.

Shaun had already been working on using Mallard for the GNOME API docs
and at the g-i hackfest last year he quickly hacked up the initial
g-ir-doc-tool to output Mallard. Because it is higher level than
DocBook and because the yelp tools already had some support for API
references, it looked much more advanced than the DocBook generator
and it was clear to us that Mallard could do the job just fine.

It's not just that it looked much nicer and was more complete, but
more importantly it reuses a big chunk of infrastructure that is
already used in GNOME and has the Documentation team behind it. Having
an intermediate format made also sense because we want the code that
is specific to each output format to duplicate as less functionality
as possible.

When I was first told of Giraffe about a year ago, it was presented as
a stop-gap for generating HTML for Python API docs from GIR files.
Canonical had decided that they needed something quickly and had no
time to work with us in something that would fit GNOME's needs in the
longer term. Have just given a look at the code in the Giraffe
repository [1] and it indeed looks to me like something temporal, the
shortest line between A and B without regards to other needs that we
have, namely eventually replacing GTK-Doc and having more than one
output format.

You mention reusing Giraffe's GIR parser, there's already a GIR parser
and an AST in GObject-Introspection that is mature, in use and being
maintained, why not reuse it and share the maintenance cost?

The improvements that you propose on top of today's GTK-Doc and
DevHelp are very interesting but I would personally prefer to get more
basic features first, so as many libraries as possible can replace
GTK-Doc and start generating API docs for languages other than C.
Maybe we can work in both directions at the same time.

So I would like to ask you how do you see rebasing your work on top of
g-ir-doc-tool and the mallard it generates, do you think it could be
worth it?

Regards,

Tomeu

[0] http://aruiz.synaptia.net/siliconisland/2012/02/gnome-development-network-an-attempt-to-improve-the-gnome-developer-experience.html

[1] http://bazaar.launchpad.net/~giraffe-dev/giraffe/trunk/files/head:/giraffe/