Re: API documentation from introspection data

[Alberto Ruiz <aruiz gnome org>]

2012/2/18 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.

I am interested in the dynamic features like doing complicated queries to show the result and being able to add comments and code examples to specific API items, writing code to output Mallard only helps if you want to still produce static content, which I think we should give up on.

 

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.

 

I am not familiar with the historiy behind giraffe, nor that I care much about the details, I just thought it was the only Python AST available, it was the one tool I knew about that could give me what I wanted. I am certainly not doing this as part of my job at Canonical.

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?

I didn't know there was a Python AST in gobject-introspection (django is one of the very few web frameworks I can cope with without tearing myself apart out of rage, so Python was a must for me).

I'm looking at it, and it might be slightly more difficult to port it to the django's data model but I'll work on it.

 

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.

Something that we both want I think is a common codebase to translate raw gtk-doc into something GJS/Python/Vala friendly. I have no plans to work on such thing though but it'll be interesting to see how we can put it somewhere we can share it.

 

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?

I can't see how I can make any use of Mallard here, my goal is to generate a dynamic site and generate the output (HTML and/or JSON) from the SQL database not the AST, for me the interesting point would be the AST (I'm already hitting the wall with giraffe as it has some bugs in some aspects so the fact that there is a maintained usptream AST is really good news).

Further down the like I'd like to enable HTML5 storage in the site so that people can use the web app even if they are offline (would make a great companion to Web (Epiphany)'s web apps support). And then we can get rid of static generation altogether. Plus you get to see all the contributed code samples and comments.

I will be migrating my stuff to giscanner.ast (big palmface on me here for not spotting this before), but I can't see how Mallard helps in any of the goals stated.

 

If you think I am wrong about Mallard not helping much, please let me know why, I might be missing something.

 

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/

-- 
Cheers,
Alberto Ruiz