Re: API documentation from introspection data
2012/2/24 Tomeu Vizoso to...@sugarlabs.org That sounds great functionality. The webapp will file bugs in BZ and attach patches to it? Or will maintainers have to go through the webapp? We can figure something out, for now it's just an idea, haven't thought of the best way to implement it. What do you think maintainers would prefer? The only thing it wouldn't be easy to provide is generating actual valid patches. Regards, Tomeu 2012/2/23 Stefan Sauer enso...@hora-obscura.de On 02/23/2012 04:18 PM, Shaun McCance wrote: snip Honestly, I think all of us (me included) are getting too hung up on the tools. What we really need is better writing. No amount of tool development is going to save you from a lack of good content. Agree, but one important part is that the tools are working in a way, that people to see them as an annoyance and turn it off. gtk-doc has quite a bit of legacy here unfortunately that is not easy to change :/ Stefan -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Tue, Feb 21, 2012 at 18:08, Stefan Sauer enso...@hora-obscura.de wrote: On 02/19/2012 03:41 PM, Shaun McCance wrote: On Sun, 2012-02-19 at 12:48 +0100, Stefan Sauer wrote: Just one thought. If people work on a next generation doc tool to take over from gtk-doc, please consider to do it without docbook xml at all. Just go from an intermediate representation to html *without* xslt. libxslt is literally dead and other processors are even slower. libxslt is not slow. The XSLT stylesheets that gtk-doc uses are slow. It's true that it's not really actively developed, but it's basically complete as an XSLT 1.0 processor and doesn't need to be constantly changed. Yes, you are partially right. But its both. For once libxslt is single threaded (also on chunked output). Just saying, that it might be a good occation to get rid of xslt processing. and XSLT stylesheets are IMHO a pain to write and even more to maintain, as soon as they are not trivial. Stefan -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Fri, Feb 24, 2012 at 11:57, Alberto Ruiz ar...@gnome.org wrote: 2012/2/24 Tomeu Vizoso to...@sugarlabs.org That sounds great functionality. The webapp will file bugs in BZ and attach patches to it? Or will maintainers have to go through the webapp? We can figure something out, for now it's just an idea, haven't thought of the best way to implement it. What do you think maintainers would prefer? The only thing it wouldn't be easy to provide is generating actual valid patches. Guess it depends on how much value they perceive that this will get them. But of course, I would expect to be easier to sell something that doesn't change their workflow, as they have to review patches anyway and git-bz makes it so much easier. Regards, Tomeu Regards, Tomeu 2012/2/23 Stefan Sauer enso...@hora-obscura.de On 02/23/2012 04:18 PM, Shaun McCance wrote: snip Honestly, I think all of us (me included) are getting too hung up on the tools. What we really need is better writing. No amount of tool development is going to save you from a lack of good content. Agree, but one important part is that the tools are working in a way, that people to see them as an annoyance and turn it off. gtk-doc has quite a bit of legacy here unfortunately that is not easy to change :/ Stefan -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On 02/23/2012 09:27 PM, Alberto Ruiz wrote: Well, this is not quite true Stefan, Right now if you want to contribute to the docs you have to do quite a bit of work (git+bugzilla workflow), even if you do this everyday, it can be quite annoying and distracting to stop everything that you are doing to ammend documentation (opening a bug request, describing it, coming up with the patch, uploading it). My intention with the web interface is to enable a contribution queue that people can edit and submit inline that doesn't require any of this and that the maintainer can review once in a while. Hi, I'd love to have a webapp. That is one thing I like in e.g. php online docs. I even proposed that in the past as a gsoc project (see https://live.gnome.org/DocumentationProject/GtkDocFuture#live_editing). Stefan 2012/2/23 Stefan Sauer enso...@hora-obscura.de mailto:enso...@hora-obscura.de On 02/23/2012 04:18 PM, Shaun McCance wrote: snip Honestly, I think all of us (me included) are getting too hung up on the tools. What we really need is better writing. No amount of tool development is going to save you from a lack of good content. Agree, but one important part is that the tools are working in a way, that people to see them as an annoyance and turn it off. gtk-doc has quite a bit of legacy here unfortunately that is not easy to change :/ Stefan -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org mailto:desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Tue, 2012-02-21 at 17:08 +0100, Stefan Sauer wrote: On 02/19/2012 03:41 PM, Shaun McCance wrote: On Sun, 2012-02-19 at 12:48 +0100, Stefan Sauer wrote: Just one thought. If people work on a next generation doc tool to take over from gtk-doc, please consider to do it without docbook xml at all. Just go from an intermediate representation to html *without* xslt. libxslt is literally dead and other processors are even slower. libxslt is not slow. The XSLT stylesheets that gtk-doc uses are slow. It's true that it's not really actively developed, but it's basically complete as an XSLT 1.0 processor and doesn't need to be constantly changed. Yes, you are partially right. But its both. For once libxslt is single threaded (also on chunked output). Sort of. It's safe to run multiple xsltTransformContexts concurrently in libxslt, but it's not a good idea to have multiple threads handle a single xsltTransformContext. (Off the top of my head, I'm almost certain the way xslt:key is implemented on-demand isn't thread-safe.) But Yelp runs multiple transforms concurrently for Mallard pages. It doesn't run a single transform to do all pages. It transforms each page on-demand, and each with a separate transform. This works fine. If yelp-build were a C program instead of a shell script, it could do the same thing to create HTML files. Just saying, that it might be a good occation to get rid of xslt processing. Well, that's certainly not going to happen any time soon for our user documentation. There are valid arguments to be made otherwise for API references, but there's also a lot of non-API-reference documentation that we need, and that we've started working on. And there are a lot of advantages to pushing everything through a single well-maintained tool chain. Incidentally, the way g-ir-doctool is implemented, it's possible to have different output formats. So if anybody wants to work on direct HTML output (or DocBook or DITA or whatever else floats your boat), you know where the code is. Honestly, I think all of us (me included) are getting too hung up on the tools. What we really need is better writing. No amount of tool development is going to save you from a lack of good content. -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On 02/23/2012 04:18 PM, Shaun McCance wrote: snip Honestly, I think all of us (me included) are getting too hung up on the tools. What we really need is better writing. No amount of tool development is going to save you from a lack of good content. Agree, but one important part is that the tools are working in a way, that people to see them as an annoyance and turn it off. gtk-doc has quite a bit of legacy here unfortunately that is not easy to change :/ Stefan -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Thu, Feb 23, 2012 at 11:15 AM, Stefan Sauer enso...@hora-obscura.de wrote: Honestly, I think all of us (me included) are getting too hung up on the tools. What we really need is better writing. No amount of tool development is going to save you from a lack of good content. Agree, but one important part is that the tools are working in a way, that people to see them as an annoyance and turn it off. gtk-doc has quite a bit of legacy here unfortunately that is not easy to change :/ A work-around that we've enacted in WebKitGTK+ is to run all steps of the gtk-doc generation during build except for the HTML generation. This allows us to turn the buildbot red when gtk-doc warnings and errors are introduced. There is a certain class of errors that is only detectable during HTML generation, but this makes most errors more obvious. HTML generation is quite slow for us. If it was faster, we would run it for every build. --Martin ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
Well, this is not quite true Stefan, Right now if you want to contribute to the docs you have to do quite a bit of work (git+bugzilla workflow), even if you do this everyday, it can be quite annoying and distracting to stop everything that you are doing to ammend documentation (opening a bug request, describing it, coming up with the patch, uploading it). My intention with the web interface is to enable a contribution queue that people can edit and submit inline that doesn't require any of this and that the maintainer can review once in a while. 2012/2/23 Stefan Sauer enso...@hora-obscura.de On 02/23/2012 04:18 PM, Shaun McCance wrote: snip Honestly, I think all of us (me included) are getting too hung up on the tools. What we really need is better writing. No amount of tool development is going to save you from a lack of good content. Agree, but one important part is that the tools are working in a way, that people to see them as an annoyance and turn it off. gtk-doc has quite a bit of legacy here unfortunately that is not easy to change :/ Stefan -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Thu, Feb 23, 2012 at 21:27, Alberto Ruiz ar...@gnome.org wrote: Well, this is not quite true Stefan, Right now if you want to contribute to the docs you have to do quite a bit of work (git+bugzilla workflow), even if you do this everyday, it can be quite annoying and distracting to stop everything that you are doing to ammend documentation (opening a bug request, describing it, coming up with the patch, uploading it). My intention with the web interface is to enable a contribution queue that people can edit and submit inline that doesn't require any of this and that the maintainer can review once in a while. That sounds great functionality. The webapp will file bugs in BZ and attach patches to it? Or will maintainers have to go through the webapp? Regards, Tomeu 2012/2/23 Stefan Sauer enso...@hora-obscura.de On 02/23/2012 04:18 PM, Shaun McCance wrote: snip Honestly, I think all of us (me included) are getting too hung up on the tools. What we really need is better writing. No amount of tool development is going to save you from a lack of good content. Agree, but one important part is that the tools are working in a way, that people to see them as an annoyance and turn it off. gtk-doc has quite a bit of legacy here unfortunately that is not easy to change :/ Stefan -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On 18 February 2012 07:47, Tomeu Vizoso to...@tomeuvizoso.net wrote: ...snip... 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. Allow me to be frank; I don't see reasons other than academics to have an intermediate format. GIR is quite simple and suitable for being its own intermediate format already I think. Going straight to HTML (or something else) is so much more easier and opens the doors for the 99% of the developer community who doesn't know docbook, Mallard, or whatever we use. 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. Let me chime in here, as the guilty party behind giraffe :-) Indeed, I threw giraffe together because at the time there was no way to generate docs for introspected languages. There were a few wip projects around, but after trying I couldn't really get any of them to work. It is true that the nature of giraffe was somewhat temporal, but I must also stress that I took some care to write it in a way that someone could pick it up and make it a complete solution. So yes, it is a minimal solution, but not necessarily where the road ends. Let me also clarify that giraffe certainly supports more than one output format. Currently it supports C and Python docs in HTML; but one could easily add any form of output (Mallard, or what ever floats your boat). Personally I want to add Vala and Seed/Gjs output (in HTML), but have never gotten around to it. 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 looked at the ast in gobject-introspection before starting giraffe. It didn't look like something that was intended as public API (nor do I think that would be a good idea). Also it did not look designed for generating documentation. Since GIR is a relatively simple XML format I decided to do my own thing. After all parsing XML in Python is not exactly rocket surgery; so the maintenance overhead of a multi-purpose public API didn't seem worthwhile for anyone. This also allowed me to expose a more DOM-like API tailored specifically for doc generation. Also - giraffe's AST is also mature and maintained - It's been running in production for over a year :-) Cheers, Mikkel ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On 02/19/2012 03:41 PM, Shaun McCance wrote: On Sun, 2012-02-19 at 12:48 +0100, Stefan Sauer wrote: Just one thought. If people work on a next generation doc tool to take over from gtk-doc, please consider to do it without docbook xml at all. Just go from an intermediate representation to html *without* xslt. libxslt is literally dead and other processors are even slower. libxslt is not slow. The XSLT stylesheets that gtk-doc uses are slow. It's true that it's not really actively developed, but it's basically complete as an XSLT 1.0 processor and doesn't need to be constantly changed. Yes, you are partially right. But its both. For once libxslt is single threaded (also on chunked output). Just saying, that it might be a good occation to get rid of xslt processing. Stefan -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Sat, 2012-02-18 at 15:00 +, 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. 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. -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On 01/13/2012 02:17 PM, Tomeu Vizoso wrote: Hi, in a bit less than a month from now there will be a hackfest on documentation in Brno [0]. Has anybody done any further work since Berlin in generating API documentation in the Mallard format from the GIR files? I plan to spend my time there on this, so would be great if I can avoid stepping on other people's toes. Regards, Tomeu [0] https://live.gnome.org/Hackfests/BrnoDocs2012 Just one thought. If people work on a next generation doc tool to take over from gtk-doc, please consider to do it without docbook xml at all. Just go from an intermediate representation to html *without* xslt. libxslt is literally dead and other processors are even slower. Having a faster way to generate the api docs would be great and ensure that not most developers build with --disable-gtkdoc and then later wonder why the docs are in such a bad shape. Stefan ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Sun, 2012-02-19 at 12:48 +0100, Stefan Sauer wrote: Just one thought. If people work on a next generation doc tool to take over from gtk-doc, please consider to do it without docbook xml at all. Just go from an intermediate representation to html *without* xslt. libxslt is literally dead and other processors are even slower. libxslt is not slow. The XSLT stylesheets that gtk-doc uses are slow. It's true that it's not really actively developed, but it's basically complete as an XSLT 1.0 processor and doesn't need to be constantly changed. -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
2012/2/19 Shaun McCance sha...@gnome.org On Sat, 2012-02-18 at 15:00 +, 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 ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Sun, Feb 19, 2012 at 16:22, Alberto Ruiz ar...@gnome.org wrote: 2012/2/19 Shaun McCance sha...@gnome.org On Sat, 2012-02-18 at 15:00 +, 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 ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Sun, Feb 19, 2012 at 10:22 AM, Alberto Ruiz ar...@gnome.org wrote: Django has its own comments app, that problem is already solved. And it's terrible. Speaking as someone who wrote the rating/comment system using the Django comments app, it's terrible. Don't think of adding any feature remotely modern, like any sort of formatting (crucial if some wants to post code samples without looking like ass), threaded replies, etc. django.contrib.comments is stuck in 2003. -- Jasper ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
2012/2/19 Tomeu Vizoso to...@tomeuvizoso.net On Sun, Feb 19, 2012 at 16:22, Alberto Ruiz ar...@gnome.org wrote: 2012/2/19 Shaun McCance sha...@gnome.org On Sat, 2012-02-18 at 15:00 +, 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 ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Sun, Feb 19, 2012 at 1:25 PM, Alberto Ruiz ar...@gnome.org wrote: 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 Well, in order to share the Language Smarts logic, we need to determine what things change per language. Note that the mallard-templates branch has a template per language, which is an approach I'm not all that fond of. I think encapsulating all the things that change between languages into a simple Python class would be better. See something like: https://github.com/magcius/gobject-introspection/commit/3d36e1f8a0d08311669023a72a2441775471ec28 (I was hacking on this to put a lot of common things in the docbook/mallard backends, which was before I realized that we were killing off the docbook writer, so the commit message is a bit outdated). Having that act directly on the AST nodes would be the best approach here. -- Jasper ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
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
Re: API documentation from introspection data
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. 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. 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? 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. 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? 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/ ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Fri, 2012-01-27 at 09:49 +0100, Tomeu Vizoso wrote: On Sat, Jan 14, 2012 at 23:30, Colin Walters walt...@verbum.org wrote: On Fri, 2012-01-13 at 14:17 +0100, Tomeu Vizoso wrote: Hi, in a bit less than a month from now there will be a hackfest on documentation in Brno [0]. Has anybody done any further work since Berlin in generating API documentation in the Mallard format from the GIR files? I don't think so...I'm not sure what state the work is in. Probably the first TODO item is to generate a TODO =) It's really great to hear you're looking at this! Shaun, do you have anything to say about this branch? http://git.gnome.org/browse/gobject-introspection/log/?h=mallard-templates Is it the way to go in your opinion or should we make a change in the direction? I do think it's the right direction, and I was happy with how it was panning out when I last worked on it. It just needs more work to get it producing really great docs. I did do work in tandem with this on an API reference extension to Mallard that allowed, for example, automatic links to be formatted as synopses. And with the conditional processing work I've been doing, it's possible to write for multiple programming languages in a single source file. The real problem with the whole concept is that the gtk-doc docs are written with the assumption that books are going to be made out of them. Whenever you have topics extracted from books, you're bound to have less than optimal results. For example, we only get docs for things like functions and signals, not the docs attached to the top of a C file. To gtk-doc, a single C file is basically a section in a book, and that section can have introductory material before the various reference subsections. To get top-notch docs for all bindings, I think we need to dogfood this with our C docs. That means removing section docs, moving conceptual information into separate pages, and writing with the assumption that references will be paged into topics that will be automatically converted for bindings. -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
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 [0] https://github.com/aruiz/GDN [1] https://launchpad.net/giraffe 2012/1/27 Tomeu Vizoso to...@tomeuvizoso.net On Sat, Jan 14, 2012 at 23:30, Colin Walters walt...@verbum.org wrote: On Fri, 2012-01-13 at 14:17 +0100, Tomeu Vizoso wrote: Hi, in a bit less than a month from now there will be a hackfest on documentation in Brno [0]. Has anybody done any further work since Berlin in generating API documentation in the Mallard format from the GIR files? I don't think so...I'm not sure what state the work is in. Probably the first TODO item is to generate a TODO =) It's really great to hear you're looking at this! Shaun, do you have anything to say about this branch? http://git.gnome.org/browse/gobject-introspection/log/?h=mallard-templates Is it the way to go in your opinion or should we make a change in the direction? Thanks, Tomeu ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
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. [0] https://github.com/aruiz/GDN [1] https://launchpad.net/giraffe 2012/1/27 Tomeu Vizoso to...@tomeuvizoso.net On Sat, Jan 14, 2012 at 23:30, Colin Walters walt...@verbum.org wrote: On Fri, 2012-01-13 at 14:17 +0100, Tomeu Vizoso wrote: Hi, in a bit less than a month from now there will be a hackfest on documentation in Brno [0]. Has anybody done any further work since Berlin in generating API documentation in the Mallard format from the GIR files? I don't think so...I'm not sure what state the work is in. Probably the first TODO item is to generate a TODO =) It's really great to hear you're looking at this! Shaun, do you have anything to say about this branch? http://git.gnome.org/browse/gobject-introspection/log/?h=mallard-templates Is it the way to go in your opinion or should we make a change in the direction? Thanks, Tomeu ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: API documentation from introspection data
On Fri, 2012-01-13 at 14:17 +0100, Tomeu Vizoso wrote: Hi, in a bit less than a month from now there will be a hackfest on documentation in Brno [0]. Has anybody done any further work since Berlin in generating API documentation in the Mallard format from the GIR files? I don't think so...I'm not sure what state the work is in. Probably the first TODO item is to generate a TODO =) It's really great to hear you're looking at this! ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
