Re: API documentation from introspection data

[Alberto Ruiz <aruiz gnome org>]

2012/2/19 Shaun McCance <shaunm gnome org>

On Sat, 2012-02-18 at 15:00 +0000, Alberto Ruiz wrote:
>
> 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,

False. Mallard is effectively a queryable node graph with marked
up text associated with each node. Any information you can extract
from the GIR to query in a database, you can embed into Mallard
and make visible to the entire processing system.

Sure, but I don't think creating a web service on top of an on disk XML file scales too well. If everytime we get a request we have to parse the mallard file and perform XQueries on it we are going to need quite some beefy machines.

 

And for user-added comments and examples, the wealth of sites using
services like Disqus shows that you don't have to throw away your
tool chain to do it. Of course, we can't use a proprietary service
like Disqus, but we can make free software to do the same thing,
and it could be reused by lots of projects. In fact, I have a
back-burner project to do just that.

Django has its own comments app, that problem is already solved.

 

I am not sure what are you proposing here guys? The more custom code we create to generate this, the less people available to help us maintain it we are going to get. I really don't see the benefits of using Mallard here at all (not saying that it couldn't be used).

You know what the really important bit here is? It's not whether we use Mallard or not, is the design of the whole site, and we are going to attract a lot less web designers if to implement each design they need to learn XQuery and whatnot. Why don't we use mature and featureful frameworks to write web services instead? Don't you think we'll be able to attract more designers and the whole thing would be easier to maintain?

Especially taking into account that I am already writing it and all I need to do now is to port it to gobject introspection's own AST. Once that's done there's not much else to maintain other than the view code and the templates.

-- 
Cheers,
Alberto Ruiz