Hi all, As you know, the new API docs[1] are generated via PDoc[2][3] from the source code. Unfortunately, though, porting over the old docs[4] is a non-trivial process, just because of the volumes involved and because frankly the old docs were pretty out of date. (I cheerfully volunteered to do it -- I'm not Core, I just help out sometimes and help moderate the lists -- completely underestimating the size of the task; and then my Real Job got Real Busy and I'm just not going to get it done alone. In fact, I've done just about as much on it as I can.)
Now YOU, in just a few minutes per day, can dramatically help Prototype's documentation by helping merge the old docs into the source (and updating them to be current as we go). There are a bunch of tickets in Lighthouse[5] related to merging the old docs in (that link will automatically search for them for you). The tickets have been divvied up into bite-sized chunks, so you can dip in and out quite easily, it's not a big commitment! Much of the work has already been done for you, by Tobie writing a script to reach into Mephisto (the CMS that handles the old API docs [and various other things]) and extracting the docs, automatically converting much of their markup into the new PDoc format. Those .pdoc files (which are just plain text) are attached to the tickets they relate to. So a lot of this is just copy-and-paste into the relevant source file. It's easy to get involved, especially if you're a Mac OS, Linux, or *nix user (but Windows users are welcome too!). Just: 1. Grab a copy of the the source: $ git clone git://github.com/sstephenson/prototype.git $ cd prototype 2. Build your local copy $ rake dist $ rake doc (You may need to install the bluecloth ruby-gem. If you find you need to install others, please post here so people know!) 3. Grab one of the "merge old docs" tickets[5] from Lighthouse 4. See if someone's already working on it (see the comments) and if not, add a comment saying you're working on it 5. Make your changes to the source. Please do take time to make sure that what you're doing is in keeping with the new PDoc formatting and such. 6. Check them by building your docs again (rake doc) 7. Build a patch: $ git add src/blah/blah.js (e.g., the file you modified) $ git commit -m "doc: blah blah blah [#123 state:resolved]" $ git format-patch origin (Note the "doc:" at the beginning of the commit line, and the "[#123 state:resolved]" at the end. The 123 should be the issue # of the issue you're fixing.) 8. Upload the patch file to the ticket. More info on getting the source and building patches and such on the Contribute page[6]. Some things to look out for in the docs: * Do the parameter names match the source? * Do the parameters have their types? * Are the examples correct? * Are the examples...overdone, overly chatty, or unrealistic -- e.g., in need of pruning? * Do all "Examples" headers use H5 (either by using an h5 element, or by using five has marks: #####)? [1] http://api.prototypejs.org [2] http://pdoc.org [3] http://groups.google.com/group/pdoc [4] http://prototypejs.org/api [5] https://prototype.lighthouseapp.com/projects/8886-prototype/tickets?q=merge+old+docs+state%3Aopen+state%3Anew&filter= [6] http://prototypejs.org/contribute If we all pitch in a few minutes here and there, we'll get the new docs up-to-scratch in terms of information in no time! Many thanks in advance to anyone who pitches in. -- T.J. :-) --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Prototype & script.aculo.us" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/prototype-scriptaculous?hl=en -~----------~----~----~----~------~----~------~--~---
