I have written an addon file for rake that turns the wxWidgets documentation into something much more Ruby like. The code has not been cleaned up or re-factored and needs some extra features added but it does quite a bit already. I have uploaded the generated documentation to my web site so people can view it. http://hailstonesoftware.com/_files/Ruby/wxruby/html/wx_contents.html. I also have a zipped version if anyone wants to download a local copy. http://hailstonesoftware.com/_files/Ruby/wxruby/wxRuby_docs.zip The docs are generated by parsing the LaTeX originals from wxWidgets and outputing a Rubyish version. These LaTeX files are then run thru tex2rtf to create the HTML docs. The attached file shows all the details, just drop it into the rake folder and add require "rake/rakedocs" to the main rakefile and also add create_documentation_tasks under all the other create_*_tasks in the main rakefile. Type rake -T to see the added tasks. All the requirements to run the doc tasks are at the top of the rakedocs.rb file. Feedback is welcome especially on the styling of the method names. I hope this email makes sense, I am half asleep but wanted to get this out for some feedback. Sean _______________________________________________ wxruby-users mailing list wxruby-users@rubyforge.org http://rubyforge.org/mailman/listinfo/wxruby-users
Sean Long wrote:> I have written an addon file for rake that turns the wxWidgets > documentation into something much more Ruby like.Very nice indeed, thank you. This is a real boost for wxruby.> The code has not been cleaned up or re-factored and needs some extra > features added but it does quite a bit already.I refactored a little while working through to understand what you did. Hopefully I''ve made your logic a little clearer. The parsing also happens to be 3-4 times faster, b/c of different uncamelcasing and taking the regex literals out of the loops. It also fixes camelcase edge cases like GetXRCID and Dos2Unix. There''s few refinements of the rake tasks - eg you can specify a custom latex macro set with ENV[''TEX2RTF_STYLESHEET'']. What we could look at next is some easy way to bundle this with our gem and tarball releases. I think it would be better to bundle only a subset of class/method documentation reflecting classes actually ported so far. The other reference docs (overviews etc) can be available on-line. What might also be nice is to have our own CSS stylesheet that gives it a wxRuby look and feel distinct from the WxWidgets style (which after a few years I am really sick of looking at...) Another small point - I wonder if we could have Wx:: prefixed to the class names in our docs? Anyway, once again, nice job. Let me know if you''re happy with my changes, and I''ll check it into CVS. cheers alex -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: rakedocs.rb Url: http://rubyforge.org/pipermail/wxruby-users/attachments/20060812/5cb1da7e/attachment.pl
> I refactored a little while working through to understand what you did. > Hopefully I''ve made your logic a little clearer. The parsing also > happens to be 3-4 times faster, b/c of different uncamelcasing and > taking the regex literals out of the loops. It also fixes camelcase edge > cases like GetXRCID and Dos2Unix.Great clean up job! It looks 100 times better now and 70 or so lines of code less. I am also glad the you could understand the mess of code, it was really just a quick proof of concept hack.> There''s few refinements of the rake tasks - eg you can specify a custom > latex macro set with ENV[''TEX2RTF_STYLESHEET''].I like that idea.> What we could look at next is some easy way to bundle this with our gem > and tarball releases. I think it would be better to bundle only a subset > of class/method documentation reflecting classes actually ported so > far. The other reference docs (overviews etc) can be available on-line.I agree with this 100%, I was going to add a list of *.tex files that not should not be processed.> What might also be nice is to have our own CSS stylesheet that gives it > a wxRuby look and feel distinct from the WxWidgets style (which after a > few years I am really sick of looking at...)The wxWidgets look is a bit dated, I may try creating a new stylesheet tonight.> Another small point - I wonder if we could have Wx:: prefixed to the > class names in our docs?I originally had that but it got redundant looking so I removed it. We could add a section at the top of each class file that shows that the class belongs to the Wx module.> Anyway, once again, nice job. Let me know if you''re happy with my > changes, and I''ll check it into CVS.I am very happy with the changes, check it in. So Kevin did give you CVS commit access? Alright! Sean
Sean Long wrote:>> I think it would be better to bundle only a subset of class/method documentation reflecting classes actually ported so far. >> > > I agree with this 100%, I was going to add a list of *.tex files that > not should not be processed. >Yep - one tricky thing is that the tex2rtf processor doesn''t seem to like single files - it relies on directives in the top document (I know nothing about tex). Another prob is the cross-references in the class docs - we don''t want dead links. Perhaps in the longer run we want to run this sort of process once to create a base set of class ref docs. These live in our VCS, and we hand-edit them to reflect wxRuby specifics (deleting irrelevant stuff, adding Ruby examples, correcting Ruby-specific method sigs etc). This is similar to what we did with the Wx header files. The question then would be what format we use as our base - what do people think about: - LaTeX? (we have it, but how many of us know LaTeX? And no ri output) - rdoc (doesn''t seem well suited for SWIGged C extensions - FXRuby get round it by maintaining a dummy set of rb files with the documentation) - rdtool (is this project still alive? can''t find much documentation) - html (easy, but not very semantic) - DocBook (very nice output, verbose to generate & edit, overkill?) None of these seems ideal. Another option would be to co-ordinate with WxWidgets and add notes directly to the base docs, like WxPerl and WxPython. But I think there are a lot of problems with this.> The wxWidgets look is a bit dated, I may try creating a new stylesheet tonight. >Attached my quick stab at it, with the dashed lines that seem obligatory in any CSS based design these days ;).> I originally had that but it got redundant looking so I removed it. We > could add a section at the top of each class file that shows that the > class belongs to the Wx module. >Might be worth adding, thanks.> I am very happy with the changes, check it in. So Kevin did give you > CVS commit access? Alright!Yes, I''m just committing fixes to the samples so Kevin can focus on the SWIG patches. cheers alex
On Sun, 2006-08-13 at 01:44 +0100, Alex Fenton wrote:> Perhaps in the longer run we want to run this sort of process once to > create a base set of class ref docs. These live in our VCS, and we > hand-edit them to reflect wxRuby specifics (deleting irrelevant stuff, > adding Ruby examples, correcting Ruby-specific method sigs etc). This is > similar to what we did with the Wx header files. The question then would > be what format we use as our base - what do people think about: > > - LaTeX? (we have it, but how many of us know LaTeX? And no ri output) > - rdoc (doesn''t seem well suited for SWIGged C extensions - FXRuby get > round it by maintaining a dummy set of rb files with the documentation) > - rdtool (is this project still alive? can''t find much documentation) > - html (easy, but not very semantic) > - DocBook (very nice output, verbose to generate & edit, overkill?)Other options would be the lightweight markup languages like markdown, textile, etc... http://en.wikipedia.org/wiki/List_of_lightweight_markup_languages Fewer tools, but FAR easier to maintain and update. To me, they fit the agility of Ruby. Kevin
> Other options would be the lightweight markup languages like markdown, > textile, etc...I think that''s an excellent idea; they seem a better fit than any of the ''formal'' doc standards I mentioned. I''d suggest textile as it has both a good ruby implementation (redcloth) and a comprehensive and clear syntax. It includes id''d paras and headings which are very useful for creating cross-refs eg to particular methods. AFAIK markdown/bluecloth doesn''t have these. If we wanted to create a PDF format for print, we could always use something like HTMLDoc (free HTML->PDF converter). I don''t personally use ri much anyway. I''ll perhaps have a shot at adapting Sean''s work to output textile. alex
On Sat, 2006-08-12 at 00:34 -0700, Sean Long wrote:> I have uploaded the generated documentation to my web site so people > can view it. > http://hailstonesoftware.com/_files/Ruby/wxruby/html/wx_contents.html.Very impressive! Kevin
Alex Fenton wrote:> I''ll perhaps have a shot at adapting Sean''s work to output textile. >Just a quick update in case anyone else is working on this - I have a pretty complete and correct WxWidgets Latex->Textile parser, I''m just working on refining the output and making build tasks. My working files attached - just for interest and comment, not quite ready for committing yet. The runnable file is ''latex-converter.rb'', ''stringhelper.rb'' and ''latex-parser.rb'' should be in the same directory. Redcloth is needed. I''ll try and finish this week. cheers alex -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: latex-converter.rb Url: http://rubyforge.org/pipermail/wxruby-users/attachments/20060815/498a74a9/attachment-0001.pl -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: latex_parser.rb Url: http://rubyforge.org/pipermail/wxruby-users/attachments/20060815/498a74a9/attachment-0002.pl -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: stringhelper.rb Url: http://rubyforge.org/pipermail/wxruby-users/attachments/20060815/498a74a9/attachment-0003.pl