Update help message for ./pants goal goals  (was ./pants goals)

./pants goals fails with a message:

BadSpecError: BUILD file does not exist at: /Users/zundel/Src/pants/goals/BUILD

Testing Done:
manual inspection of the help output.

Bugs closed: 644

Reviewed at https://rbcommons.com/s/twitter/r/1128/
Publishing doc fixes

Further cleanups to the publishing doc to avoid sharp edges and fix a formatting error.

Testing Done:
Eyeballed:
./build-support/bin/publish_docs.sh -o

Reviewed at https://rbcommons.com/s/twitter/r/1136/
Remove hack to add java_sources in context

Testing Done:
Yes:
https://travis-ci.org/pantsbuild/pants/builds/37349364

Maunally generated idea for
./pants goal idea testprojects/src/scala/com/pants/testproject/javasources:javasources and
./pants goal idea testprojects/src/scala/com/pants/testproject/javasources:javasources --idea-intransitive

Both have dependent java_sources targets configured in generated Project Structure.

With Eric's hack to add java_sources in ide_gen for scala_library, we no longer need the java_sources to be added to the self.context targets.
https://github.com/pantsbuild/pants/blob/master/src/python/pants/backend/jvm/tasks/ide_gen.py#L552

Reviewed at https://rbcommons.com/s/twitter/r/1130/
When a jvm doc tool (e.g. scaladoc) fails in combined mode, throw an exception.  Log runs of jvmdoc.  Eliminate unnecessary dict lookup.

Testing Done:
Ran tests.

Reviewed at https://rbcommons.com/s/twitter/r/1116/
Added documentation on the difference between a pants.pex for testing and production

Bugs closed: 648

Reviewed at https://rbcommons.com/s/twitter/r/1134/
BUILD Dictionary vs factory functions: doc the class, not the factory

Wondering why the docs for 'bundle' say 'Return a factory method that can
create bundles rooted at the parse context path.' ? This is why.

This change...
introduces another @manaul.builddict() param, factory. The builddict
goal, if it sees a symbol tagged @manual.builddict(factory=True), hopes
the factory is a class method and doc's the attached class instead of
the factory function itself.

Testing Done:
https://travis-ci.org/pantsbuild/pants/builds/37459441

Bugs closed: 580

Reviewed at https://rbcommons.com/s/twitter/r/1126/