2012/2/18 Tomeu Vizoso <to...@tomeuvizoso.net> > On Fri, Jan 27, 2012 at 16:33, Alberto Ruiz <ar...@gnome.org> wrote: > > > > > > 2012/1/27 Alberto Ruiz <ar...@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
_______________________________________________ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
