With the big One-Oh on it''s way, I''m thinking we should perhaps start to work on the documentation some more. The RDoc format is perfectly fine, and does its job beautifully, but I think it doesn''t quite reflect the whizbang value that rails has, especially for newcomers. As one who has looked at the api docs almost daily for several months, I feel quite comfortable navigating it and finding what I want, but I remember the first time I saw the docs I thought that they looked kinda non-pretty. That is of course a purely personal opinion, but I''d like to know how newcomers (and old-skoolers) feel about the current docs? Apart from the looks, which we can argue to death I guess, there''s a few thing we can''t do, most importantly there''s no form of search, apart from whatever search capabilities ones browser has. There''s also no way of commenting anything, in case there''s a particular gotcha or common tips related to a specific method. Looking at the documentation for other opensource projects, such as PHP[1], postgres[2], mysql[3] and to some degree the various java based projects, they all have, at least IMHO, very clear and useful documentation, the comments on the php docs are quite useful (but perhaps thats because php is a mess) a lot of times. Now, obviously we''d want to keep the smoothness that rdoc provides by creating docs from the src comments, but I''m thinking it should be possible to import that smoothly into a Rails based application which will add things such as searching, user additions/annotations/comments and other wonderful things we can dream up. Perhaps by exporting the RDoc to xml and importing those into our übercool documentor rails app (which has yet to exist! ;)) What ideas and opinions do you guys have on the documentation? How can we make it better? And I''m not just thinking about the actual written documentation, but also the presentation/functionality of it? (Apologies for the long-ish mail, and yes, I am volunteering for this ;)) [1]: http://www.php.net/manual/en/ [2]: http://www.postgresql.org/docs/ [3]: http://dev.mysql.com/doc/mysql/en/index.html
mike-1VQMlerLD/jR7s880joybQ@public.gmane.org
2005-Mar-10 12:42 UTC
Re: (Online) documentation for 1.0
As a newcomer to Rails (less than 2 days so Im not sure Im qualified to comment), I think the OnLamp is good as far as it goes. But what I think would be really usefull is documentation along the lines of the ''Design Patterns'' GoF book. That would be the most succinct way of explaining to newbies the most common patterns in the system. Common ''cookbook'' solutions would be great too. e.g. this is how you create a login system, this is how you push back an image, etc.. Also if ''Active*'' is "core" then don''t bother calling it ''Active*'' ... its just part of the rails subsytem. The proliferation of terms reminds me of the jakarta apache page, where you can choose to download a bizarre number of different packages. I dont knowi if they''re "core" or not. Just my two [pound|euro|cent|] worth. Rds Mike> With the big One-Oh on it''s way, I''m thinking we should perhaps start > to work on the documentation some more. > > The RDoc format is perfectly fine, and does its job beautifully, but I > think it doesn''t quite reflect the whizbang value that rails has, > especially for newcomers. > As one who has looked at the api docs almost daily for several months, > I feel quite comfortable navigating it and finding what I want, but I > remember the first time I saw the docs I thought that they looked > kinda non-pretty. That is of course a purely personal opinion, but I''d > like to know how newcomers (and old-skoolers) feel about the current > docs? > > Apart from the looks, which we can argue to death I guess, there''s a > few thing we can''t do, most importantly there''s no form of search, > apart from whatever search capabilities ones browser has. There''s also > no way of commenting anything, in case there''s a particular gotcha or > common tips related to a specific method. > Looking at the documentation for other opensource projects, such as > PHP[1], postgres[2], mysql[3] and to some degree the various java > based projects, they all have, at least IMHO, very clear and useful > documentation, the comments on the php docs are quite useful (but > perhaps thats because php is a mess) a lot of times. > > Now, obviously we''d want to keep the smoothness that rdoc provides by > creating docs from the src comments, but I''m thinking it should be > possible to import that smoothly into a Rails based application which > will add things such as searching, user additions/annotations/comments > and other wonderful things we can dream up. > Perhaps by exporting the RDoc to xml and importing those into our > übercool documentor rails app (which has yet to exist! ;)) > > What ideas and opinions do you guys have on the documentation? How can > we make it better? And I''m not just thinking about the actual written > documentation, but also the presentation/functionality of it? > > (Apologies for the long-ish mail, and yes, I am volunteering for this ;)) > > [1]: http://www.php.net/manual/en/ > [2]: http://www.postgresql.org/docs/ > [3]: http://dev.mysql.com/doc/mysql/en/index.html > _______________________________________________ > Rails mailing list > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > http://lists.rubyonrails.org/mailman/listinfo/rails >
On Thu, 10 Mar 2005 12:42:40 -0000 (GMT), mike-1VQMlerLD/jR7s880joybQ@public.gmane.org <mike-1VQMlerLD/jR7s880joybQ@public.gmane.org> wrote:> As a newcomer to Rails (less than 2 days so Im not sure Im qualified to > comment), I think the OnLamp is good as far as it goes. But what I > think would be really usefull is documentation along the lines of the > ''Design Patterns'' GoF book. That would be the most succinct way of > explaining to newbies the most common patterns in the system. Common > ''cookbook'' solutions would be great too. e.g. this is how you create a > login system, this is how you push back an image, etc..Yes, I think the current documentation "gems" (no relation to rubygems) is a little too spread out, making it hard(er) for newcomers to find the relevant/good stuff. In my opinion a good documentation system should look something like this: * Installation * General info about the framework, methodlogies for developing with it, how it all connects/works together * Detailed information about each framework, its concepts, how you work with it ** specific info on certain things, such as Routes, caching etc * "Typical problems/solutions" - eg. cookbook-style texts on best practices for security, performance and so on * ... (All of those is currently intervened between the wiki, the hierki manuals and the various READMEs. Collecting those, and keeping them up to date would be a fair amount of work, but beneficial to users) * Method/class reference, not much unlike rails.rubyonrails.com is today, but with searching abilities etc (I guess that goes for everything) Or is the general consensus that what is currently there is "good enough"? -j
* Johan S?rensen (johans-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org) [050310 09:03]:> (All of those is currently intervened between the wiki, the hierki > manuals and the various READMEs. Collecting those, and keeping them up > to date would be a fair amount of work, but beneficial to users) > * Method/class reference, not much unlike rails.rubyonrails.com is > today, but with searching abilities etc (I guess that goes for > everything) > > Or is the general consensus that what is currently there is "good enough"?On the contrary, while Rails documentation is better than most open source projects'' documentation, I personally think you''re on the right track here. Rick -- http://www.rickbradley.com MUPRN: 61 | attempt to bridge part random email haiku | of the beginning of the | gap fail with loki.
Rick Bradley wrote:> > * Johan S?rensen (johans-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org) [050310 09:03]: > > (All of those is currently intervened between the wiki, the hierki > > manuals and the various READMEs. Collecting those, and keeping them up > > to date would be a fair amount of work, but beneficial to users) > > * Method/class reference, not much unlike rails.rubyonrails.com is > > today, but with searching abilities etc (I guess that goes for > > everything) > > > > Or is the general consensus that what is currently there is > "good enough"? > > On the contrary, while Rails documentation is better than most open > source projects'' documentation, I personally think you''re on the right > track here.I agree on both counts -- its better than most, and needs to be better still. I think a good start would be a roadmap into the existing docs -- sort of like an annotated table of contents. It would be one place you could go to get an overview glance of all the features and facilities of Rails with hyperlinks for each to the docs the explain it, and the tutorials and howtos the use it. Curt
On Thu, 10 Mar 2005 11:48:21 -0600, Curt Hibbs <curt-fk6st7iWb8MAvxtiuMwx3w@public.gmane.org> wrote:> I think a good start would be a roadmap into the existing docs -- sort of > like an annotated table of contents. It would be one place you could go to > get an overview glance of all the features and facilities of Rails with > hyperlinks for each to the docs the explain it, and the tutorials and howtos > the use it.Yes, that would be a good start I guess. Allthough I wonder if it wouldn''t be better to jump straight to the issue and start working on The One Manual to Rule Them All right away. Then take on the API docs are freshen them up after that. But interest seems slim? Maybe I should just get starting on it by myself and hope others will chime in eventually.. -j
> Yes, that would be a good start I guess. Allthough I wonder if it > wouldn''t be better to jump straight to the issue and start working on > The One Manual to Rule Them All right away. Then take on the API docs > are freshen them up after that.I would definitely like the idea of better interface for the documentation. Comments and search would be important additions. Please do press on. It''s a must, though, that the process is fully automatic. And not just a one time import, but capable of getting updated frequently. -- David Heinemeier Hansson, http://www.basecamphq.com/ -- Web-based Project Management http://www.rubyonrails.org/ -- Web-application framework for Ruby http://www.loudthinking.com/ -- Broadcasting Brain
On Fri, 11 Mar 2005 11:19:48 +0100, David Heinemeier Hansson> It''s a must, though, that the process is fully automatic. And not just > a one time import, but capable of getting updated frequently.Yes, absolutely! Otherwise we''ll quickly end up with old docs.. I''m contemplating on what the best way to handle that would be, import xml exported from RDoc? I''ve never liked parsing xml, just to throw it into a db... Perhaps it''s possible to create a custom format for RDoc which, together with activerecord, could insert it into a db? hmm, I must admit I''m not really sure how to handle that right now, anyone wants to chime in? j
Johan Sörensen wrote:> > On Thu, 10 Mar 2005 11:48:21 -0600, Curt Hibbs <curt-fk6st7iWb8MAvxtiuMwx3w@public.gmane.org> wrote: > > I think a good start would be a roadmap into the existing docs > -- sort of > > like an annotated table of contents. It would be one place you > could go to > > get an overview glance of all the features and facilities of Rails with > > hyperlinks for each to the docs the explain it, and the > tutorials and howtos > > the use it. > > Yes, that would be a good start I guess. Allthough I wonder if it > wouldn''t be better to jump straight to the issue and start working on > The One Manual to Rule Them All right away. Then take on the API docs > are freshen them up after that. > > But interest seems slim? Maybe I should just get starting on it by > myself and hope others will chime in eventually..The reason I made my suggestion above was because it could have a major impact on usability in the shortest amount of time and least amount of work. Obviously, there is much more to do afterwards, but I still think this is a good place to start. Probably just as important (or maybe more important) is a search capability. Curt
Johan Sörensen wrote:> Perhaps by exporting the RDoc to xml and importing those into our > übercool documentor rails app (which has yet to exist! ;))I''ve played with this a bit. REXML handles the produced xml quite nicely. It might be worth investigating whether AR would be required at all for handling the actual docs.> What ideas and opinions do you guys have on the documentation? How can > we make it better? And I''m not just thinking about the actual written > documentation, but also the presentation/functionality of it?I''m a big fan of php.net documentation * most functions show example usage, including input and output * great 404 handling. try php.net/anyfunctionname_or_section_name On the nice-to-have list: * clean urls (not sure what the best approach is) * persistence of urls. Currently the anchors generated by rdoc vary from one version to the next. While I''m far from mastering Rails, I''m interested in helping out any way I can. -- Lee
Curt Hibbs wrote:>Johan Sörensen wrote: > > >>On Thu, 10 Mar 2005 11:48:21 -0600, Curt Hibbs <curt-fk6st7iWb8MAvxtiuMwx3w@public.gmane.org> wrote: >> >> >>>I think a good start would be a roadmap into the existing docs >>> >>> >>-- sort of >> >> >>>like an annotated table of contents. It would be one place you >>> >>> >>could go to >> >> >>>get an overview glance of all the features and facilities of Rails with >>>hyperlinks for each to the docs the explain it, and the >>> >>> >>tutorials and howtos >> >> >>>the use it. >>> >>> >>Yes, that would be a good start I guess. Allthough I wonder if it >>wouldn''t be better to jump straight to the issue and start working on >>The One Manual to Rule Them All right away. Then take on the API docs >>are freshen them up after that. >> >>But interest seems slim? Maybe I should just get starting on it by >>myself and hope others will chime in eventually.. >> >> > >The reason I made my suggestion above was because it could have a major >impact on usability in the shortest amount of time and least amount of work. >Obviously, there is much more to do afterwards, but I still think this is a >good place to start. > >Probably just as important (or maybe more important) is a search capability. > >Curt >It seems worth working on three activities in parallel: - review/indexing of existing documentation - defining ''ideal'' documentation structure, and populating it - choosing delivery technologies. In my view the delivery technologies should cater for on-line and off-line use, and there should be three levels of documentation - tutorial, reference, and API. Justin
The PHP online documentation is a great example. My favorite aspect is being able to comment on the entries, also. The little recipes people write in there are priceless. -raymond On Mar 11, 2005, at 9:43 AM, Lee O''Mara wrote:> Johan Sörensen wrote: > >> Perhaps by exporting the RDoc to xml and importing those into our >> übercool documentor rails app (which has yet to exist! ;)) > > I''ve played with this a bit. REXML handles the produced xml quite > nicely. It might be worth investigating whether AR would be required > at all for handling the actual docs. > >> What ideas and opinions do you guys have on the documentation? How can >> we make it better? And I''m not just thinking about the actual written >> documentation, but also the presentation/functionality of it? > > I''m a big fan of php.net documentation > > * most functions show example usage, including input and output > * great 404 handling. try php.net/anyfunctionname_or_section_name > > On the nice-to-have list: > > * clean urls (not sure what the best approach is) > * persistence of urls. Currently the anchors generated by rdoc vary > from one version to the next. > > While I''m far from mastering Rails, I''m interested in helping out any > way I can. > > -- > Lee > _______________________________________________ > Rails mailing list > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > http://lists.rubyonrails.org/mailman/listinfo/rails >
Justin Forder wrote:> In my view the delivery technologies should cater for on-line and > off-line use, and there should be three levels of documentation - > tutorial, reference, and API.I agree with the point about online & offline use. Can you elaborate about the differences you see between reference and API documentation? -- Lee
Lee O''Mara wrote:> Justin Forder wrote: > >> In my view the delivery technologies should cater for on-line and >> off-line use, and there should be three levels of documentation - >> tutorial, reference, and API. > > > I agree with the point about online & offline use. > > Can you elaborate about the differences you see between reference and > API documentation?Good point, because the API documentation for Rails is rather different from the API documentation I am used to in the Java world. If you take successful open-source Java frameworks (Struts, Spring, Hibernate) as an example, each has a reference manual which is the definitive source of information on what the framework can do for you, and how to use it. The API documentation exists, and you have the option of having the source as well if you wish, but in normal day-to-day use you should not have to look at these. I''m a beginner with Rails, currently working through Four Days on Rails, and it''s interesting that every reference to further detail from that tutorial is a reference to RDoc API documentation. There *is* good reference-style documentation there, but it is constrained by being subordinate to the namespace/class structure of the code, and it seems to be intended as a starting point, rather than as a full reference. It''s reasonable for the API documentation to assume that the reader can continue to browse the documentation for individual methods... but which of these express a contract with the framework user, vs. being internal and subject to change at the whim of the framework developer? Sorry if this is rather inarticulate - I just know that some ways of packaging documentation *do* work, and that I have had problems finding the information I need for Rails. Justin
I am in my 4th week of learning ruby/rails and this is my first post to the mailing list. I am attempting to migrate over to rails from php. I am coming along pretty well, learning more every day. One of the things I personally would find useful is what someone mentioned earlier: documentation similar to the php style. I find that when i need to accomplish something new in php, I can simply search the docs and come up with a good starting place of functions that may be what I need. Not only that but there is usually a code snipet or two that do exactly what I am looking for in the first place right in the user comments. From what I can tell thus far rails is far superior in its design. PHP wins on documentation, however that seems likely as rails is a fairly new project anyway and moving rapidly. The code snipets and search features are the keys to what make it easy for me to whip something up quickly. I guess the downside is the possibility of code degrading over time as with php''s inconsistency, but I have not done any research on that phenomenon. Personally, the way I learn is by seeing something in action. I rarely look at the prototype of a function/method to figure out how it works (for the better or worse!). I found the LoginGenerator code helpful as a starting point for learning how rails works, but before that had read pages and pages of rails articles and still didnt grasp the concept. Just my 2 cents. Joe Noon Justin Forder wrote:> Lee O''Mara wrote: > >> Justin Forder wrote: >> >>> In my view the delivery technologies should cater for on-line and >>> off-line use, and there should be three levels of documentation - >>> tutorial, reference, and API. >> >> >> >> I agree with the point about online & offline use. >> >> Can you elaborate about the differences you see between reference and >> API documentation? > > > Good point, because the API documentation for Rails is rather different > from the API documentation I am used to in the Java world. > > If you take successful open-source Java frameworks (Struts, Spring, > Hibernate) as an example, each has a reference manual which is the > definitive source of information on what the framework can do for you, > and how to use it. The API documentation exists, and you have the option > of having the source as well if you wish, but in normal day-to-day use > you should not have to look at these. > > I''m a beginner with Rails, currently working through Four Days on Rails, > and it''s interesting that every reference to further detail from that > tutorial is a reference to RDoc API documentation. There *is* good > reference-style documentation there, but it is constrained by being > subordinate to the namespace/class structure of the code, and it seems > to be intended as a starting point, rather than as a full reference. > > It''s reasonable for the API documentation to assume that the reader can > continue to browse the documentation for individual methods... but which > of these express a contract with the framework user, vs. being internal > and subject to change at the whim of the framework developer? > > Sorry if this is rather inarticulate - I just know that some ways of > packaging documentation *do* work, and that I have had problems finding > the information I need for Rails. > > Justin > > _______________________________________________ > Rails mailing list > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > http://lists.rubyonrails.org/mailman/listinfo/rails > >
Justin Forder wrote:> If you take successful open-source Java frameworks (Struts, Spring, > Hibernate) as an example, each has a reference manual which is the > definitive source of information on what the framework can do for you, > and how to use it. The API documentation exists, and you have the option > of having the source as well if you wish, but in normal day-to-day use > you should not have to look at these.I think you can see a hint of the division you''re speaking of if you compare the docs for a class vs. the docs for method (especially the main classes: AR, AV, AC,..) There''s a page or two giving you an overview of how to use the class, followed by (relatively limited, very specific) docs for each method.> I''m a beginner with Rails, currently working through Four Days on Rails, > and it''s interesting that every reference to further detail from that > tutorial is a reference to RDoc API documentation. There *is* good > reference-style documentation there, but it is constrained by being > subordinate to the namespace/class structure of the code, and it seems > to be intended as a starting point, rather than as a full reference.I agree about the namespace/class structure being an awkward fit for those unfamiliar with the "lay of the land". I''m sure there''s a more intuitive way to expose the same information in a more accessible manner.> It''s reasonable for the API documentation to assume that the reader can > continue to browse the documentation for individual methods... but which > of these express a contract with the framework user, vs. being internal > and subject to change at the whim of the framework developer?While I''m sure changes are bound to occur(especially before 1.0), I''m not particularly concerned with the distinction you make.. Maybe I don''t see any documented (public) methods that could change that a framework-user wouldn''t like to know about?> Sorry if this is rather inarticulate - I just know that some ways of > packaging documentation *do* work, and that I have had problems finding > the information I need for Rails.I think it''s a debate worth having. You''re far from the first person to cite that issue. -- Lee
Johan Sörensen said something:> Apart from the looks, which we can argue to death I guess, there''s a > few thing we can''t do, most importantly there''s no form of search,Try google(site:rubyonrails.com rss builder). maybe all we need is a way of googling from the pages? iain
Lee O''Mara wrote:> Justin Forder wrote: > >> If you take successful open-source Java frameworks (Struts, Spring, >> Hibernate) as an example, each has a reference manual which is the >> definitive source of information on what the framework can do for >> you, and how to use it. The API documentation exists, and you have >> the option of having the source as well if you wish, but in normal >> day-to-day use you should not have to look at these. > > I think you can see a hint of the division you''re speaking of if you > compare the docs for a class vs. the docs for method (especially the > main classes: AR, AV, AC,..) There''s a page or two giving you an > overview of how to use the class, followed by (relatively limited, > very specific) docs for each method.Agreed.>> I''m a beginner with Rails, currently working through Four Days on >> Rails, and it''s interesting that every reference to further detail >> from that tutorial is a reference to RDoc API documentation. There >> *is* good reference-style documentation there, but it is constrained >> by being subordinate to the namespace/class structure of the code, >> and it seems to be intended as a starting point, rather than as a >> full reference. > > I agree about the namespace/class structure being an awkward fit for > those unfamiliar with the "lay of the land". I''m sure there''s a more > intuitive way to expose the same information in a more accessible manner.I think the distinction is between requirements- (or task-) oriented documentation and solution-oriented documentation. A requirement is met by a collaboration between classes, so it doesn''t fit well into the RDoc structure.>> It''s reasonable for the API documentation to assume that the reader >> can continue to browse the documentation for individual methods... >> but which of these express a contract with the framework user, vs. >> being internal and subject to change at the whim of the framework >> developer? > > While I''m sure changes are bound to occur(especially before 1.0), I''m > not particularly concerned with the distinction you make.. Maybe I > don''t see any documented (public) methods that could change that a > framework-user wouldn''t like to know about?Unless this distinction is clear it will not be possible to refactor the framework without breaking applications. With Ruby, anyone can override anything. Framework users need to know what the legitimate extension points are. Then the users who find it necessary to hook into the ''internals'' will know that it is *their* responsibility to make changes as and when the framework is refactored. Justin
I haven''t tried this but it is a ruby based http://gonzui.sourceforge.net/ What''s gonzui? gonzui is a source code search engine for accelerating open source software development. In the open source software development, programmers frequently refer to source codes written by others. Our goal is to help programmers develop programs effectively by creating a source code search engine that covers vast quantities of open source codes available on the Internet. Lee O''Mara wrote:s> Johan Sörensen wrote: > >> Perhaps by exporting the RDoc to xml and importing those into our >> übercool documentor rails app (which has yet to exist! ;)) > > > I''ve played with this a bit. REXML handles the produced xml quite > nicely. It might be worth investigating whether AR would be required > at all for handling the actual docs. > >> What ideas and opinions do you guys have on the documentation? How can >> we make it better? And I''m not just thinking about the actual written >> documentation, but also the presentation/functionality of it? > > > I''m a big fan of php.net documentation > > * most functions show example usage, including input and output > * great 404 handling. try php.net/anyfunctionname_or_section_name > > On the nice-to-have list: > > * clean urls (not sure what the best approach is) > * persistence of urls. Currently the anchors generated by rdoc vary > from one version to the next. > > While I''m far from mastering Rails, I''m interested in helping out any > way I can. > > -- > Lee > _______________________________________________ > Rails mailing list > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org > http://lists.rubyonrails.org/mailman/listinfo/rails >
Lee O''Mara wrote:> Justin Forder wrote: > >> If you take successful open-source Java frameworks (Struts, Spring, >> Hibernate) as an example, each has a reference manual which is the >> definitive source of information on what the framework can do for you, >> and how to use it. The API documentation exists, and you have the >> option of having the source as well if you wish, but in normal >> day-to-day use you should not have to look at these. > > I think you can see a hint of the division you''re speaking of if you > compare the docs for a class vs. the docs for method (especially the > main classes: AR, AV, AC,..) There''s a page or two giving you an > overview of how to use the class, followed by (relatively limited, very > specific) docs for each method. > >> I''m a beginner with Rails, currently working through Four Days on >> Rails, and it''s interesting that every reference to further detail >> from that tutorial is a reference to RDoc API documentation. There >> *is* good reference-style documentation there, but it is constrained >> by being subordinate to the namespace/class structure of the code, and >> it seems to be intended as a starting point, rather than as a full >> reference.One thing struck me in the last couple of days - there''s a README file for ActiveRecord (the first thing you see when you browse the RDoc), but there isn''t one for ActionPack. Adding one could make a big difference - the whole introduction to Rails (with the diagram showing how the parts work together) could be in there. Justin
On Wed, 16 Mar 2005 19:22:03 +0000, Justin Forder <justin-zSfPWr5aQuznITO/+xaoB7VCufUGDwFn@public.gmane.org> wrote:> One thing struck me in the last couple of days - there''s a README file > for ActiveRecord (the first thing you see when you browse the RDoc), but > there isn''t one for ActionPack.Look in the leftside frame: http://rails.rubyonrails.com/files/vendor/actionpack/README.html
On Fri, 11 Mar 2005 12:43:27 -0500, Lee O''Mara <lee-O8glSrxzjJo@public.gmane.org> wrote:> I''ve played with this a bit. REXML handles the produced xml quite > nicely. It might be worth investigating whether AR would be required at > all for handling the actual docs.Yeah, it might be a useless step to dump the RDocs into a database, just parsing the rdoc generated xml at runtime would probably be smoother (perhaps caching it so we don''t have to do it everytime someone hits the page). Would you be interested in sharing/contributing code? To kickstart this project.. -- johan-s
Johan Sörensen wrote:> On Wed, 16 Mar 2005 19:22:03 +0000, Justin Forder > <justin-zSfPWr5aQuznITO/+xaoB7VCufUGDwFn@public.gmane.org> wrote: > >>One thing struck me in the last couple of days - there''s a README file >>for ActiveRecord (the first thing you see when you browse the RDoc), but >>there isn''t one for ActionPack. > > Look in the leftside frame: > http://rails.rubyonrails.com/files/vendor/actionpack/README.htmlWell, that''s good, and http://ap.rubyonrails.com/ is exactly as I would like it to be, but the documentation in the gem (I''m on Rails 0.10.0) C:\ruby\lib\ruby\gems\1.8\doc\actionpack-1.5.0\rdoc\index.html doesn''t have the README, the CHANGELOG, or the RUNNING_UNIT_TESTS file. Justin
Johan Sörensen wrote:> On Fri, 11 Mar 2005 12:43:27 -0500, Lee O''Mara <lee-O8glSrxzjJo@public.gmane.org> wrote: > >>It might be worth investigating whether AR would be required at >>all for handling the actual docs. > > Yeah, it might be a useless step to dump the RDocs into a database, > just parsing the rdoc generated xml at runtime would probably be > smoother (perhaps caching it so we don''t have to do it everytime > someone hits the page).I agree, straight XML might be easier. Two desires suggested to me that a DB might still be required: 1) the desire for persistence between successive rdoc generations 2) the desire for a stable hook from which to hang user comments> Would you be interested in sharing/contributing code? To kickstart > this project..It was just a proof of concept, but if you guys are up for good laugh, sure I''ll share. I''m quite interested in seeing progress made on this project. -- Lee O''Hara