And I got this lousy LatexParser. Ah well... A new cut of the automatic WxRuby documentation is now viewable online at http://www.pressure.to/wxruby/. There''s also a pdf version http://www.pressure.to/wxruby/wxruby.pdf [3MB, 751 pages!] and a tarball http://www.pressure.to/wxruby/wxruby2.tar.gz [1.3MB] In terms of output, it''s no advance on what Sean has already done. What''s slightly interesting is that it''s produced by parsing the Latex WxWidgets docs to Textile before rendering to HTML using RedCloth. Textile is a lightweight markup language, and seems maybe a good fit for storing and editing our docs in our VCS. There''s a link to the Textile source of each page at the bottom. I don''t think the time is quite right to commit the docs in yet - we probably want to tweak the automated output and stabilise the API first. But, soon, maybe. I''d like to commit the Latex parsing and Textile outputting code to CVS, but not sure where to put it. It''s rather too large to put in the rake files (400+ LOC) - I''d rather keep the rake files fairly clean and focussed on the actual build tasks. Suggestions... maybe a /utils directory? Or /lib - but don''t include this with the gem bundle? Suggestions for improvements very welcome cheers alex
On Wed, 2006-08-16 at 23:11 +0100, Alex Fenton wrote:> A new cut of the automatic WxRuby documentation is now viewable online at > http://www.pressure.to/wxruby/.Cool. This seems like a good direction for us. A few minor suggestions/comments: Red on white is probably hard for some folks to read. And on my system, it is hard to see the difference between visited and unvisited links. I assume at some point it will be possible to hyperlink the return value classes. So in Window#get_position, you could click on Point to get to the Point class. It will be interesting to see how much we have to censor out, such as the discussion of compilers in TextCtrl.> I''d like to commit the Latex parsing and Textile outputting code to CVS, > but not sure where to put it. It''s rather too large to put in the rake > files (400+ LOC) - I''d rather keep the rake files fairly clean and > focussed on the actual build tasks. Suggestions... maybe a /utils > directory? Or /lib - but don''t include this with the gem bundle?Perhaps we should create a doc/ directory? Kevin
Kevin Smith wrote:> On Wed, 2006-08-16 at 23:11 +0100, Alex Fenton wrote: > >> A new cut of the automatic WxRuby documentation is now viewable online at >> http://www.pressure.to/wxruby/. >> > > I assume at some point it will be possible to hyperlink the return value > classes. So in Window#get_position, you could click on Point to get to > the Point class. >Not to mention that most everything is untyped in Ruby so the function parameters may need to be removed or changed somehow. Not sure. Also, we need to remove the ''Bogus'' class from the list. Roy
On Wed, 2006-08-16 at 21:04 -0400, Roy Sutton wrote:> Not to mention that most everything is untyped in Ruby so the function > parameters may need to be removed or changed somehow. Not sure.I thought that, but looking at it, I think I like the way it is. You need to know what types get passed and returned. Maybe they just need to be italics, smaller, fainter, or otherwise flagged as being metadata about the parameters.> Also, we need to remove the ''Bogus'' class from the list.Yup. Kevin
Kevin Smith wrote:> Red on white is probably hard for some folks to read. And on my system, > it is hard to see the difference between visited and unvisited links. >OK. Is red on white a known accessibility issue? Or do we just need to darken the shade a little bit? This is all in the CSS, so easily tweaked.> I assume at some point it will be possible to hyperlink the return value > classes. So in Window#get_position, you could click on Point to get to > the Point class. >Have added this.> It will be interesting to see how much we have to censor out, such as > the discussion of compilers in TextCtrl. >Some of the incline C++ code also plays havoc with Textile''s formatter, so no bad thing ...> Perhaps we should create a doc/ directory? >Sounds good. Will commit shortly. [Following Roy''s post]> Not to mention that most everything is untyped in Ruby so the function > parameters may need to be removed or changed somehow. Not sure.I agree in theory - but practically, as Kevin says,WxRuby functions expect particular types (as in classes) of arguments and will choke on other stuff. The typemaps seem to make the API more strictly typed than we want, but we can come back to that. I''ve gone with putting the type ''hints'' in a fainter colour. as a side note, much as I like ruby, having seen CPP type handling via WxRuby there are things I like. Whether types are defined in terms of classes (boring old-fashioned) or in terms of capabilities/methods (fashionable ''duck-typing''), methods still need to be coded to do something useful with particular types of arguments. Overloading seems, superficially at least, to be quite a neat way of doing this. cheers alex
On Fri, 2006-08-18 at 00:55 +0100, Alex Fenton wrote:> Kevin Smith wrote: > > Red on white is probably hard for some folks to read. And on my system, > > it is hard to see the difference between visited and unvisited links. > > > OK. Is red on white a known accessibility issue? Or do we just need to > darken the shade a little bit?As with anything, opinions vary. Supposedly one study showed 10% of people had trouble reading red on white. A different site I saw recommended it as a good choice for color-blind folks. Personally, I find it usable but a bit straining. A darker red would definitely help, so that might be the first thing to try.> > I assume at some point it will be possible to hyperlink the return value > > classes. So in Window#get_position, you could click on Point to get to > > the Point class. > > > Have added this.Sweet.> > Perhaps we should create a doc/ directory? > > > Sounds good. Will commit shortly.I just noticed that the gem chapter of the pickaxe book recommends creating a docs/ directory (as opposed to doc/). If that''s really a gem standard, we should obey. Otherwise, doc/ seems to be slightly more common. Kevin
> I just noticed that the gem chapter of the pickaxe book recommends > creating a docs/ directory (as opposed to doc/). If that''s really a gem > standard, we should obey. Otherwise, doc/ seems to be slightly more > common. >I agree. As far as I can tell RubyGems doesn''t provide any doc except to rdoc. But I will check the relevant bit of the pickaxe when I get back to London this evening. Suggest I hold off doing a commit until after alpha. Am happy to host the interim docs online for the time being, if that''s useful. Will update the index page with a rider that they''re autogenerated and so methods may be missing or have different signatures. alex
Kevin Smith
2006-Aug-18 14:14 UTC
[Wxruby-users] Where to host the docs, and wxruby.org (was: all I wanted was a class reference...)
On Fri, 2006-08-18 at 06:12 +0100, Alex Fenton wrote:> Suggest I hold off doing a commit until after alpha. Am happy to host > the interim docs online for the time being, if that''s useful. Will update > the index page with a rider that they''re autogenerated and so methods > may be missing or have different signatures.That sounds good. But since we will be publishing the URL, I would prefer that it be a relatively permanent location. Should we push it to our rubyforge web space? I was going to ask about grabbing wxruby.org/com and having the docs there. Then I realized that I should just grab the domains myself before someone else does. So we now have wxruby.com and wxruby.org that point to our project page (which points to the wiki). So, can you add a link to your new API docs on the wiki front page? Kevin
Sean Long
2006-Aug-18 15:04 UTC
[Wxruby-users] Where to host the docs, and wxruby.org (was: all I wanted was a class reference...)
> I was going to ask about grabbing wxruby.org/com and having the docs > there. Then I realized that I should just grab the domains myself before > someone else does. So we now have wxruby.com and wxruby.org that point > to our project page (which points to the wiki).Good idea, I thought about that other day but forgot to bring it up. I think that simple act just bumped up the status of the project, well at least in some potential users minds it might have. Sean
Kevin Smith wrote:> That sounds good. But since we will be publishing the URL, I would > prefer that it be a relatively permanent location. Should we push it to > our rubyforge web space? >Yes, sounds like a good idea. I''ve just tested publishing to the website and it works fine. Will do a publish once I''ve cleaned up the doc index page.> So we now have wxruby.com and wxruby.org that point > to our project page (which points to the wiki). >Neat.> So, can you add a link to your new API docs on the wiki front page? >Yep, will update wiki once the stuff is uploaded. cheers alex
I finally got around to checking out the docs and I think they look good. The HTML generated is much cleaner than what is produced with tex2rtf. I did notice that on CommandEvent (http://www.pressure.to/wxruby/commandevent.html) a few of the event handlers did not get renamed. I also like how the wxPython/wxPerl remarks are removed, this makes it look more customized to the wxRuby project. Nice work Sean On 8/17/06, Alex Fenton <alex at pressure.to> wrote:> > > I just noticed that the gem chapter of the pickaxe book recommends > > creating a docs/ directory (as opposed to doc/). If that''s really a gem > > standard, we should obey. Otherwise, doc/ seems to be slightly more > > common. > > > I agree. As far as I can tell RubyGems doesn''t provide any doc > except to rdoc. But I will check the relevant bit of the pickaxe when > I get back to London this evening. > > Suggest I hold off doing a commit until after alpha. Am happy to host > the interim docs online for the time being, if that''s useful. Will update > the index page with a rider that they''re autogenerated and so methods > may be missing or have different signatures. > > alex > > > _______________________________________________ > wxruby-users mailing list > wxruby-users at rubyforge.org > http://rubyforge.org/mailman/listinfo/wxruby-users >