I found a few small things, which were mostly there before your patch. As someone who has learned everything they know from the docs, I can say this is an improvement on a somewhat confusing section. Benjy said yesterday that pants py is deprecated in favor of repl, which I had never heard of. Might that warrant a mention here?
Since we are here, the sentence before this contains an issue "with targets for binaries, libraries, and use it to build" needs an 'or' somewhere.
When published, "run goal", "test goal" and "binary goal" have both words italicized and linked, which looks confusingly like a recommendation to enter "run goal" into the prompt.
doc: Python doc, don't use twitter/commons as example
Review Request #654 — Created July 10, 2014 and submitted
Back when Pants' source code lived in twitter/commons, it made sense to use example code from there. Nowadays, not so much. Use Pants' own src/python/example instead. Instead of having sample code in the doc, "include" from src/python/example; that's easier to keep correct.