Conor Hunt
2005-Oct-31 02:47 UTC
Rannotate - User submitted notes for rdoc generated documentation
Hi Rails folks, I just recently started with ROR and I began missing the PHP sytle online documentation, with it''s useful user submitted notes: http://www.php.net/manual/en/ So I''ve written a small application, Rannotate, that does something similar for rdoc generated documentation. Rannotate consists of a rails app and a custom rdoc template. You execute rdoc with the custom template, you start the rails application and voila.. you have user annotated rdoc. For an example check out the Rails API documentation with Rannotate: http://rails.outertrack.com/rails/index.html The project is hosted at rubyforge: http://rannotate.rubyforge.org Once this has been through a couple of iterations, has some more features (RSS feeds etc), and becomes stable enough I hope that it could be used for http://api.rubyonrails.com/. Any thoughts on that? is it useful? Big thanks to Jamis Buck, http://jamis.jamisbuck.org/, for his excellent rdoc template. Mine is a customization of his. cheers. -- Conor
Ezra Zygmuntowicz
2005-Oct-31 05:01 UTC
Re: Rannotate - User submitted notes for rdoc generated documentation
Conor-
Very cool. Useful too. The docs need something like this to
become a one stop shopping for docs and tricks.
-Ezra
On Oct 30, 2005, at 6:47 PM, Conor Hunt wrote:
> Hi Rails folks,
>
> I just recently started with ROR and I began missing the PHP sytle
> online documentation, with it''s useful user submitted notes:
> http://www.php.net/manual/en/
>
> So I''ve written a small application, Rannotate, that does
something
> similar for rdoc generated documentation. Rannotate consists of a
> rails app and a custom rdoc template. You execute rdoc with the custom
> template, you start the rails application and voila.. you have user
> annotated rdoc.
>
> For an example check out the Rails API documentation with Rannotate:
> http://rails.outertrack.com/rails/index.html
>
> The project is hosted at rubyforge:
> http://rannotate.rubyforge.org
>
> Once this has been through a couple of iterations, has some more
> features (RSS feeds etc), and becomes stable enough I hope that it
> could be used for http://api.rubyonrails.com/. Any thoughts on that?
> is it useful?
>
> Big thanks to Jamis Buck, http://jamis.jamisbuck.org/, for his
> excellent rdoc template. Mine is a customization of his.
>
> cheers.
>
> --
>
> Conor
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>
>
-Ezra Zygmuntowicz
WebMaster
Yakima Herald-Republic Newspaper
ezra-gdxLOakOTQ9oetBuM9ipNAC/G2K4zDHf@public.gmane.org
509-577-7732
Nathaniel S. H. Brown
2005-Oct-31 05:24 UTC
RE: Rannotate - User submitted notes for rdoc generateddocumentation
This is pretty sweet. What I would really like is to port the documentation entirely over to a PHP style documentation system whereby it has no frames and is able to be full length of the page with similar functions on the left side. Also, one thing to note is that I was only able to get into Class documentation comments, it would be nice to see individual method comments as well. Warmest regards, Nathan. -------------------------------------------------------------- Nathaniel S. H. Brown Toll Free 1.877.4.INIMIT Inimit Innovations Phone 604.724.6624 www.inimit.com Fax 604.444.9942> -----Original Message----- > From: rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > [mailto:rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org] On Behalf Of Conor Hunt > Sent: October 30, 2005 6:48 PM > To: rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > Subject: [Rails] Rannotate - User submitted notes for rdoc > generateddocumentation > > Hi Rails folks, > > I just recently started with ROR and I began missing the PHP > sytle online documentation, with it''s useful user submitted notes: > http://www.php.net/manual/en/ > > So I''ve written a small application, Rannotate, that does > something similar for rdoc generated documentation. Rannotate > consists of a rails app and a custom rdoc template. You > execute rdoc with the custom template, you start the rails > application and voila.. you have user annotated rdoc. > > For an example check out the Rails API documentation with Rannotate: > http://rails.outertrack.com/rails/index.html > > The project is hosted at rubyforge: > http://rannotate.rubyforge.org > > Once this has been through a couple of iterations, has some > more features (RSS feeds etc), and becomes stable enough I > hope that it could be used for http://api.rubyonrails.com/. > Any thoughts on that? > is it useful? > > Big thanks to Jamis Buck, http://jamis.jamisbuck.org/, for > his excellent rdoc template. Mine is a customization of his. > > cheers. > > -- > Conor > _______________________________________________ > Rails mailing list > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > http://lists.rubyonrails.org/mailman/listinfo/rails >
Conor Hunt
2005-Oct-31 05:49 UTC
Re: Rannotate - User submitted notes for rdoc generateddocumentation
Thanks for the feedback. I''m definitely looking for more feedback and bug reports like this! I agree a no-frames version would be great. I did it with the frame at first because it is much easier to insert dynamic content into the display that way. All of the documentation is static and there is a single javascript onLoad inserted in main frame during the rdoc generation. Whenever the main frame changes this causes the comments frame to reload. I haven''t figured out an easy way to insert the dynamically generated comments at the bottom of the static page yet. If I can do that then I can remove the frame. For individual methods there is a ''show user notes'' link beside each method in the body of the class documentation. Right now that is the only way to get to them Unfortunately when you click on a method name in the frame that displays all of the methods I get a link like blah#M000021 in the main window. I don''t know what method name that maps to so I can''t display the method comments. This should be solvable with some more javascript and some parsing of the link in the methods list though. Generally I wish that rdoc used ERb templates instead. I''m not sure how hard it would be to do, but I''d like to extend rdoc with an ERb style generator. -- Conor On 10/31/05, Nathaniel S. H. Brown <nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org> wrote:> This is pretty sweet. What I would really like is to port the documentation > entirely over to a PHP style documentation system whereby it has no frames > and is able to be full length of the page with similar functions on the left > side. > > Also, one thing to note is that I was only able to get into Class > documentation comments, it would be nice to see individual method comments > as well. > > Warmest regards, > Nathan. > > -------------------------------------------------------------- > Nathaniel S. H. Brown Toll Free 1.877.4.INIMIT > Inimit Innovations Phone 604.724.6624 > www.inimit.com Fax 604.444.9942 > > > > -----Original Message----- > > From: rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > > [mailto:rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org] On Behalf Of Conor Hunt > > Sent: October 30, 2005 6:48 PM > > To: rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > > Subject: [Rails] Rannotate - User submitted notes for rdoc > > generateddocumentation > > > > Hi Rails folks, > > > > I just recently started with ROR and I began missing the PHP > > sytle online documentation, with it''s useful user submitted notes: > > http://www.php.net/manual/en/ > > > > So I''ve written a small application, Rannotate, that does > > something similar for rdoc generated documentation. Rannotate > > consists of a rails app and a custom rdoc template. You > > execute rdoc with the custom template, you start the rails > > application and voila.. you have user annotated rdoc. > > > > For an example check out the Rails API documentation with Rannotate: > > http://rails.outertrack.com/rails/index.html > > > > The project is hosted at rubyforge: > > http://rannotate.rubyforge.org > > > > Once this has been through a couple of iterations, has some > > more features (RSS feeds etc), and becomes stable enough I > > hope that it could be used for http://api.rubyonrails.com/. > > Any thoughts on that? > > is it useful? > > > > Big thanks to Jamis Buck, http://jamis.jamisbuck.org/, for > > his excellent rdoc template. Mine is a customization of his. > > > > cheers. > > > > -- > > Conor > > _______________________________________________ > > Rails mailing list > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > > http://lists.rubyonrails.org/mailman/listinfo/rails > > > > _______________________________________________ > Rails mailing list > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > http://lists.rubyonrails.org/mailman/listinfo/rails >
Nathaniel S. H. Brown
2005-Oct-31 06:47 UTC
RE: Rannotate - User submitted notes for rdocgenerateddocumentation
Ideally if Rdoc would be able to export into a XML style document, you would be able to run it though an XSLT parser and create any type of document you want. This would faciliate the ability to translate it into any style of document, as well as being inserted and read into other applications. The Erb style templates would be nice, but still would rely on the user to create a new tier to create an XML document.> Thanks for the feedback. I''m definitely looking for more > feedback and bug reports like this! > > I agree a no-frames version would be great. I did it with the > frame at first because it is much easier to insert dynamic > content into the display that way. All of the documentation > is static and there is a single javascript onLoad inserted in > main frame during the rdoc generation. Whenever the main > frame changes this causes the comments frame to reload. > > I haven''t figured out an easy way to insert the dynamically > generated comments at the bottom of the static page yet. If I > can do that then I can remove the frame. >Ajax would work beautifully for this. Create an empty div, and run an AJAX query against a database for the comments and populate the DIV with the content.> For individual methods there is a ''show user notes'' link > beside each method in the body of the class documentation. > Right now that is the only way to get to them >Ahh, I didn''t see this. This should be by default loaded when you click on the links within the method frame. See my comment below for how this can occur if not through a direct link.> Unfortunately when you click on a method name in the frame > that displays all of the methods I get a link like > blah#M000021 in the main window. I don''t know what method > name that maps to so I can''t display the method comments. > This should be solvable with some more javascript and some > parsing of the link in the methods list though. >Ajax would definitely come in handy with something like this. Put a second event in your onload that grabs the window.location and displays the docs based on the entire URL would be a very simple method of doing so.> Generally I wish that rdoc used ERb templates instead. I''m > not sure how hard it would be to do, but I''d like to extend > rdoc with an ERb style generator.Warmest regards, Nathan. -------------------------------------------------------------- Nathaniel S. H. Brown Toll Free 1.877.4.INIMIT Inimit Innovations Phone 604.724.6624 www.inimit.com Fax 604.444.9942
Conor Hunt
2005-Oct-31 17:41 UTC
Re: Rannotate - User submitted notes for rdocgenerateddocumentation
Great suggestions. I think the AJAX should be no problem and I will probably implement that. The other option that I am considering is to make the documentation fully dynamic, so that instead of generating HTML I take the output of the Rdoc parsing and insert it into a database. This way I can implement great features using Rails and have the documentation output however I want. I just need to spend some time understanding the code_object.rb from Rdoc and what sort of database structure could hold it. -- Conor On 10/31/05, Nathaniel S. H. Brown <nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org> wrote:> Ideally if Rdoc would be able to export into a XML style document, you would > be able to run it though an XSLT parser and create any type of document you > want. This would faciliate the ability to translate it into any style of > document, as well as being inserted and read into other applications. > > The Erb style templates would be nice, but still would rely on the user to > create a new tier to create an XML document. > > > > Thanks for the feedback. I''m definitely looking for more > > feedback and bug reports like this! > > > > I agree a no-frames version would be great. I did it with the > > frame at first because it is much easier to insert dynamic > > content into the display that way. All of the documentation > > is static and there is a single javascript onLoad inserted in > > main frame during the rdoc generation. Whenever the main > > frame changes this causes the comments frame to reload. > > > > I haven''t figured out an easy way to insert the dynamically > > generated comments at the bottom of the static page yet. If I > > can do that then I can remove the frame. > > > > Ajax would work beautifully for this. Create an empty div, and run an AJAX > query against a database for the comments and populate the DIV with the > content. > > > For individual methods there is a ''show user notes'' link > > beside each method in the body of the class documentation. > > Right now that is the only way to get to them > > > > Ahh, I didn''t see this. This should be by default loaded when you click on > the links within the method frame. See my comment below for how this can > occur if not through a direct link. > > > Unfortunately when you click on a method name in the frame > > that displays all of the methods I get a link like > > blah#M000021 in the main window. I don''t know what method > > name that maps to so I can''t display the method comments. > > This should be solvable with some more javascript and some > > parsing of the link in the methods list though. > > > > Ajax would definitely come in handy with something like this. Put a second > event in your onload that grabs the window.location and displays the docs > based on the entire URL would be a very simple method of doing so. > > > Generally I wish that rdoc used ERb templates instead. I''m > > not sure how hard it would be to do, but I''d like to extend > > rdoc with an ERb style generator. > > Warmest regards, > Nathan. > > -------------------------------------------------------------- > Nathaniel S. H. Brown Toll Free 1.877.4.INIMIT > Inimit Innovations Phone 604.724.6624 > www.inimit.com Fax 604.444.9942 > > > _______________________________________________ > Rails mailing list > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > http://lists.rubyonrails.org/mailman/listinfo/rails >