Documentation? The documentation I use for Capistrano is the source. Even then, I need to use a lot of grep, since it's hard to know which file really defines the underlying method.
Capistrano is great, but, the documentation really suffers. If you just want to use the standard recipes, it's easy enough. But, if you want to make your own or change things, you need to grep the source. I would consider good documentation to be: * Something like api.rubyonrails.com * It should be generated from RDoc. * Consisting of: ** All of the included tasks. The description could be simply the 'desc', and the source can be included in the HTML (just like RDoc) for further details. The source is very clear. ** All of the methods designed to be called from a deploy file. That is, the RDoc doesn't need to show Capistrano internals, it does need to show things like 'before' 'put' and 'run', along with all of their options and perhaps an example. ** All the vars that the standard tasks define. So, it seems like the key here is not writing more documentation, but getting RDoc to work with Capistrano. Specifically: * Being able to run RDoc (or similar) on a Capistrano recipe file. * Being able to distinguish Capistrano methods designed to be called directly from the recipe file, and RDoc those only, distinct from Capistrano internals. I think getting RDoc or a similar tool to automate this is 100% the way to go. On May 20, 11:41 am, Lee Hambley <[email protected]> wrote: > I spotted this via my standing search for "capistrano" with google..... I'd > love to see how many people want to see better documentation, and > suggestions for where we could strengthen things. > > - > http://rails.uservoice.com/pages/10012-rails/suggestions/98521-better... > > Do we need more documentation on any of the following? Core code, source > modules, advanced stuff about user shells, user names, more resources about > keys, deprec, sprinkle, the list is endless, suggestions welcome. > > - Lee --~--~---------~--~----~------------~-------~--~----~ To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/capistrano -~----------~----~----~----~------~----~------~--~---
