Re: API documentation from introspection data
- From: Tomeu Vizoso <tomeu tomeuvizoso net>
- To: Alberto Ruiz <aruiz gnome org>
- Cc: Shaun McCance <shaunm gnome org>, desktop-devel-list <desktop-devel-list gnome org>
- Subject: Re: API documentation from introspection data
- Date: Sun, 19 Feb 2012 16:49:49 +0100
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
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!
] [Thread Prev