Help Prototype in a few minutes per day
1 view
Skip to first unread message
T.J. Crowder
Nov 16, 2009, 10:49:05 AM11/16/09
to Prototype & script.aculo.us
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. :-)
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. :-)
T.J. Crowder
Nov 17, 2009, 2:19:01 PM11/17/09
to Prototype & script.aculo.us
Thank you "Rumble" for being the first to pitch in[1][2]!! Very much
appreciated!
[1] https://prototype.lighthouseapp.com/projects/8886/tickets/934
[2] https://prototype.lighthouseapp.com/projects/8886/tickets/935
-- T.J.
> [5]https://prototype.lighthouseapp.com/projects/8886-prototype/tickets?q...
appreciated!
[1] https://prototype.lighthouseapp.com/projects/8886/tickets/934
[2] https://prototype.lighthouseapp.com/projects/8886/tickets/935
-- T.J.
Иван Жеков
Nov 17, 2009, 7:16:32 PM11/17/09
to prototype-s...@googlegroups.com
on windows it's quite tricky to rake the stuff.
I was required to install maruku gem to rake doc and even then I wasn't able to do so
or something like it.
I will reinstall the tools and see if I am able to fix things.
I was required to install maruku gem to rake doc and even then I wasn't able to do so
syntax error, unexpected $end, expecting ')' obj.sub!('...', 'тАж') if obj.is_a?(String)
or something like it.
I will reinstall the tools and see if I am able to fix things.
2009/11/17 T.J. Crowder <t...@crowdersoftware.com>
--~--~---------~--~----~------------~-------~--~----~
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 prototype-s...@googlegroups.com
To unsubscribe from this group, send email to prototype-scripta...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/prototype-scriptaculous?hl=en
-~----------~----~----~----~------~----~------~--~---
T.J. Crowder
Nov 20, 2009, 7:09:51 AM11/20/09
to Prototype & script.aculo.us
Hi,
Yeah, at the moment, it's a real pain to do this stuff on Windows. I
really wish it weren't, I would have made a lot more progress with the
time I had to work on it.
If you come up with a working combination of gems and such, please do
post back and share what you did for the benefit of others trying to
do the same thing.
Cheers,
-- T.J. :-)
> > prototype-scripta...@googlegroups.com<prototype-scriptaculou s%2Bunsu...@googlegroups.com>
Yeah, at the moment, it's a real pain to do this stuff on Windows. I
really wish it weren't, I would have made a lot more progress with the
time I had to work on it.
If you come up with a working combination of gems and such, please do
post back and share what you did for the benefit of others trying to
do the same thing.
Cheers,
-- T.J. :-)
Bertrand
Nov 20, 2009, 10:27:30 AM11/20/09
to Prototype & script.aculo.us
That, sir, is awesome. Count me in.
Радослав Станков
Nov 21, 2009, 6:18:20 PM11/21/09
to Prototype & script.aculo.us
Count me in too :)
I have done several tries tonight, and will try to continue tomorrow.
Just wanted to give several tips.
- ##### Something generates h5 with id="something"
- it's easy to instead of
$ git add src/blah/blah.js (e.g., the file you modified)
$ git commit -m "doc: blah blah blah [#123 state:resolved]"
you could just write
$ git commit -am "doc: blah blah blah [#123 state:resolved]"
(am) just add to the commit any changes you made on a file already
into the repo (it won't add new files)
p.s. is http://pdoc.org down only for me or is generally down ?!
I have done several tries tonight, and will try to continue tomorrow.
Just wanted to give several tips.
- ##### Something generates h5 with id="something"
- it's easy to instead of
$ git add src/blah/blah.js (e.g., the file you modified)
$ git commit -m "doc: blah blah blah [#123 state:resolved]"
$ git commit -am "doc: blah blah blah [#123 state:resolved]"
(am) just add to the commit any changes you made on a file already
into the repo (it won't add new files)
p.s. is http://pdoc.org down only for me or is generally down ?!
Tobie Langel
Nov 21, 2009, 7:26:35 PM11/21/09
to Prototype & script.aculo.us
Thank you, much appreciated!
pdoc.org does indeed appear to be down. Will investigate.
Best,
Tobie
> p.s. ishttp://pdoc.orgdown only for me or is generally down ?!
pdoc.org does indeed appear to be down. Will investigate.
Best,
Tobie
lun...@gmail.com
Nov 22, 2009, 4:31:33 AM11/22/09
to prototype-s...@googlegroups.com
Hi,
I followed your instructions up to
rake doc
which resulted (with --trace) in:
(in /home/luniki/Projects/prototype)
** Invoke doc (first_time)
** Invoke doc:build (first_time)
** Invoke doc:require (first_time)
** Execute doc:require
** Execute doc:build
mkdir -p /home/luniki/Projects/prototype/test/unit/tmp
rm -rf /home/luniki/Projects/prototype/doc
Parsing source files:
/home/luniki/Projects/prototype/test/unit/tmp/prototype.temp.js.
Processing. 98%
rake aborted!
rake aborted!
wrong number of arguments (1 for 2)
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`initialize'
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`new'
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`terminal_failures'
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`map!'
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`terminal_failures'
/home/luniki/Projects/prototype/vendor/pdoc/lib/pdoc/parser.rb:81:in
`failures'
/home/luniki/Projects/prototype/vendor/pdoc/lib/pdoc/parser.rb:103:in
`expected_string'
/home/luniki/Projects/prototype/vendor/pdoc/lib/pdoc/parser.rb:65:in
`message'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:2078:in
`standard_exception_handling'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:2023:in `top_level'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:2001:in `run'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:2068:in
`standard_exception_handling'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:1998:in `run'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/bin/rake:31
/usr/bin/rake:19:in `load'
/usr/bin/rake:19
What's wrong with this?
--luniki
I followed your instructions up to
rake doc
which resulted (with --trace) in:
(in /home/luniki/Projects/prototype)
** Invoke doc (first_time)
** Invoke doc:build (first_time)
** Invoke doc:require (first_time)
** Execute doc:require
** Execute doc:build
mkdir -p /home/luniki/Projects/prototype/test/unit/tmp
rm -rf /home/luniki/Projects/prototype/doc
Parsing source files:
/home/luniki/Projects/prototype/test/unit/tmp/prototype.temp.js.
Processing. 98%
rake aborted!
rake aborted!
wrong number of arguments (1 for 2)
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`initialize'
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`new'
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`terminal_failures'
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`map!'
/usr/lib/ruby/gems/1.8/gems/treetop-1.4.2/lib/treetop/runtime/compiled_parser.rb:47:in
`terminal_failures'
/home/luniki/Projects/prototype/vendor/pdoc/lib/pdoc/parser.rb:81:in
`failures'
/home/luniki/Projects/prototype/vendor/pdoc/lib/pdoc/parser.rb:103:in
`expected_string'
/home/luniki/Projects/prototype/vendor/pdoc/lib/pdoc/parser.rb:65:in
`message'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:2078:in
`standard_exception_handling'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:2023:in `top_level'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:2001:in `run'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:2068:in
`standard_exception_handling'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/lib/rake.rb:1998:in `run'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.7/bin/rake:31
/usr/bin/rake:19:in `load'
/usr/bin/rake:19
What's wrong with this?
--luniki
T.J. Crowder
Dec 5, 2009, 8:31:29 AM12/5/09
to Prototype & script.aculo.us
Hi all,
FYI, documentation tickets now have their own home:
https://prototype.lighthouseapp.com/projects/42103-prototype-documentation/tickets
The tickets I mentioned before have been moved over to it.
-- T.J. :-)
> [5]https://prototype.lighthouseapp.com/projects/8886-prototype/tickets?q...
FYI, documentation tickets now have their own home:
https://prototype.lighthouseapp.com/projects/42103-prototype-documentation/tickets
The tickets I mentioned before have been moved over to it.
-- T.J. :-)
Reply all
Reply to author
Forward
0 new messages