Re: API documentation from introspection data

[Tomeu Vizoso <tomeu tomeuvizoso net>]

On Sun, Feb 19, 2012 at 16:22, Alberto Ruiz <aruiz gnome org> wrote:
>
>
> 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.

Normally people use caches for those.

>> 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).

So the good thing about Mallard from my POV is precisely that it's
code that I need and that somebody else is going to maintain. I get
tools for converting Mallard to other formats and an app to index and
display it, with at least as many features as what gtk-doc and devhelp
have ever had.

Now, you may say that we don't need gtk-doc or devhelp-like
functionality and that may end up being true, but right now from
asking to a couple of library maintainers around here, people are not
sold yet on the idea of using a web app.

In any case, it will be good if your webapp shares some code with
g-ir-doc-tool. I look forward to see a first prototype!

Regards,

Tomeu