Re: API documentation from introspection data

[Alberto Ruiz <aruiz gnome org>]

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

That's because what you care about is converting gtk-doc to Mallard and then to other formats, which is okay, but it's not the problem I'm trying to solve, which is exactly my original point. So I think you guys should keep working on the Mallard tooling, and I should keep working on my web app and figure out which things have common ground for us to work together.

 

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.

Library maintainers are not my target audience, but up to some extend this is good news because it means we are both covering different grounds/needs :-)

 

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!

Totally!

I think that a tool to convert the doc string into something C/Python/Vala/GJS friendly (with links to each node) would be nice. If it had some sort of integration with the AST it would be nice so that we could somehow dynamically assign http/mallard xrefs. I am not sure what the right approach is but this is a problem that we both have I think. There's some code to do that in giraffe for C and Python IIRC.

 

Regards,

Tomeu

-- 
Cheers,
Alberto Ruiz