doc: dust off the Task Developer's Guide :-) rm the "pagerank" example

Review Request #1074 — Created Sept. 24, 2014 and submitted

benjyw, ity

Our page about how to develop a Task described "science-era" Pants.

Removed a lot of what's there; it talked about APIs that have since become new and improved.

Removed the "pagerank" example. :-( When I started on this change, I thought I was gonna update this example and maybe move it to examples/src/... so it would get exercised and not drift back into b0rken-ness . But it's kind of a weird example--it doesn't really care about products, it doesn't do "the usual" things with deps. So I find myself deleting it... but with some misgivings, because it's cool. If someone wants to do the work to modernize it and move it to examples, I'll happily code review :-)

Replaced copy-pasted code snippets with "includes" from live tasks.
Maybe this won't drift out of date so easily from now on.
(Didn't add includes for the JVM section, just a TODO. But did remove now-obsolete sample code.)

rm'd some redundant-and-obsolete info from the Internals page, replacing w/link to Task Developer's guide. (Thanks to Mateo for spotting this!) The basic concepts were OK, but the details, yikes. Internals page had info about GroupTask, which Task Developers page lacked... so move it over.

Made some guesses a la "if I was about to write a task, what would I prrrrobably want to know how to do." Added some blurbs around those things. Not necessarily complete, but at least enough to nudge folks in the right direction.

  1. I don't officially vote but this gets a Ship It! from me, with a few notes. I implemented the PageRank during my first week with Pants. After I was done, I still felt like I didn't have any idea how to add a new Task that did actual work. This introduces all the new concepts and is much more helpful. A big improvement already.

  2. src/python/pants/docs/dev_tasks.rst (Diff revision 1)

    s/run/runs/ for agreement with verbs.

  3. src/python/pants/docs/dev_tasks.rst (Diff revision 1)

    This and the context link below render oddly to me. The link is followed by the '.Task' string, so it ends with 'tasks.task.Task'. I couldn't find this being done elsewhere. Maybe this conventionally indicates an instance and everyone knows that but me :)

  4. src/python/pants/docs/dev_tasks.rst (Diff revision 1)

    s/more than task/more than one task/

  5. src/python/pants/docs/dev_tasks.rst (Diff revision 1)

    Pants will happily let you require non-installed require_data. No error is raised unless you attempt to act upon that non-existant type later in execute.

  1. Go fish. I've never written a task myself, I don't want to sign off on something I'm not comfortable with.

    1. Sorry for the noise. If it's any consolation, you're the Author of plenty of code in /tasks/ directories.

  1. Ship It!

Review request changed

Status: Closed (submitted)