doc: if rbt fails, don't give up and workaround. things to try

Reviewed at https://rbcommons.com/s/twitter/r/1048/
remove page target whose README.md does not exist

Reviewed at https://rbcommons.com/s/twitter/r/1046/
Correct old examples/ reference - use testprojects/ copy.

Testing Done:
CI went green here: https://travis-ci.org/pantsbuild/pants/builds/35687312

Bugs closed: 585

Reviewed at https://rbcommons.com/s/twitter/r/1049/
Improve python CI robustness.

Ensure all tests/python targets are selected when dividing up unit
and integration tests - no longer use aggregator targets as a guide.

This change leaves the aggregators in-place and just divorces CI from
them to ensure we always CI all test targets.

 build-support/bin/ci.sh | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

Testing Done:
Locally:
$ ./build-support/bin/ci.sh

Travis went green here: https://travis-ci.org/pantsbuild/pants/builds/35691561

Bugs closed: 586

Reviewed at https://rbcommons.com/s/twitter/r/1050/
jvm_binary init handling of name param made more sense before kwargs idiom

...but now it's probably better not to mention it in the sig

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

Reviewed at https://rbcommons.com/s/twitter/r/1054/
Fix coverage tests on MacOS

Testing Done:
build-support/bin/ci.sh on my mac laptop.

ci green @ https://travis-ci.org/pantsbuild/pants/builds/35870205

Bugs closed: 595

Reviewed at https://rbcommons.com/s/twitter/r/1057/
Add a CI action to support CI against OSX.

This adds a sync action run on any push to pantsbuild/pants
master that replaces pantsbuild/pants-for-travis-osx-ci master
modifying the active .travis.yml to trigger an OSX CI run.

Testing Done:
Normal CI went green here: https://travis-ci.org/pantsbuild/pants/builds/35900516

OSX CI went green here: https://travis-ci.org/pantsbuild/pants-for-travis-osx-ci/builds/35899630
Via:
```console
$ set | grep GH_ | cut -d= -f1
GH_EMAIL
GH_TOKEN
GH_USER
$ ./build-support/bin/ci-sync.sh
[jsirois/pants-for-travis-osx-ci/sync 9a13170] Prepare pants OSX mirror for CI.
 Author: Pants CI <pants-ci@googlegroups.com>
 1 file changed, 13 insertions(+), 40 deletions(-)
 rewrite .travis.yml (87%)
Counting objects: 37, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (18/18), done.
Writing objects: 100% (23/23), 3.05 KiB | 0 bytes/s, done.
Total 23 (delta 14), reused 9 (delta 3)
To https://github.com/pantsbuild/pants-for-travis-osx-ci.git
 + 888c8bf...9a13170 HEAD -> master (forced update)
$ gitbinfo
* jsirois/pants-for-travis-osx-ci/sync 9a13170 [pants/master: ahead 2] Prepare pants OSX mirror for CI.
$ git slog -2
commit 9a13170039dfe93824fd9487f78f96c134e09d88
Author: Pants CI <pants-ci@googlegroups.com>
Date:   Sun Sep 21 20:22:52 2014 -0600

    Prepare pants OSX mirror for CI.

 .travis.yml | 35 ++++-------------------------------
 1 file changed, 4 insertions(+), 31 deletions(-)

commit f4cb72ba4cc48ec5f6a23c86903fe83b735a8f3f
Author: John Sirois <john.sirois@gmail.com>
Date:   Sun Sep 21 17:30:29 2014 -0600

    Add a CI action to support CI against OSX.
...
```

Bugs closed: 596

Reviewed at https://rbcommons.com/s/twitter/r/1058/
Sync the OSX CI eagerly and add diagnostics.

Move the OSX CI sync up-front to leverage parallelism
instead of waiting on the whole local build matrix to complete.

Also add diagnostics that record why the sync is skipped if
skipped in addition to making skipping & syncing decisions more
robust and explicit.

Testing Done:
CI away here already shows proper fork sync-skipping diagnostic: https://travis-ci.org/pantsbuild/pants/builds/35967008
This will have to land on pantsbuild/pants master to vet fully.

Bugs closed: 599

Reviewed at https://rbcommons.com/s/twitter/r/1064/
Fixup ci-sync.sh to cover committer ident.

Testing Done:
None - can only be tested on pantsbuild.pants master, but in response to this failure: https://travis-ci.org/pantsbuild/pants/jobs/35969933
CI did go green here though - so nothing horribly more broken: https://travis-ci.org/pantsbuild/pants/builds/35972662

Bugs closed: 600

Reviewed at https://rbcommons.com/s/twitter/r/1065/
Remove recommendation of manual edits to the pushdb

The manual-edits-to-the-pushdb approach gets a bit too down and dirty. Remove the recommendation in favor of resetting and using --publish-override.

Reviewed at https://rbcommons.com/s/twitter/r/1056/
Use `.travis.yml` notifications for `.travis.osx.yml`

This copies over the notifications settings of the main
`.travis.yml` to `.travis.osx.yml` so that we can maintain
them centrally.

The change also tweaks the commit message to aid in quick
linking / correspondence of a pantsbuild/pants-for-travis-osx-ci
commit to a pantsbuild/pants commit.

Testing Done:
Ad hoc:
```bash
$ venv_setup pyyaml PyYAML && source ~/.pythons/venvs/pyyaml/bin/activate
(pyyaml)$ python << EOF
> import yaml
> with open('.travis.yml') as fp:
>   config = yaml.safe_load(fp)
> with open('.travis.osx.yml') as fp:
>   config_new = yaml.safe_load(fp)
> config_new['notifications'] = config['notifications']
> with open('.travis.new.yml', 'w') as fp:
>   yaml.safe_dump(config_new, fp)
> EOF
(pyyaml)$ cat .travis.new.yml
language: objective-c
notifications:
  email: [john.sirois@gmail.com, lhosken@twitter.com, zundel@squareup.com, benjyw@gmail.com,
    areitz@twitter.com]
script: 'sw_vers

  python --version

  java -version

  ./build-support/bin/ci.sh -d

  '
```

Bugs closed: 601

Reviewed at https://rbcommons.com/s/twitter/r/1067/
remove some more redundant docstrings

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

Reviewed at https://rbcommons.com/s/twitter/r/1035/
new "sitegen" goal in internal backend

Defines a new "sitegen" goal. It's the start of a static site generator for Pants docs.

We don't want to ship this goal to all Pants users.
We do want to use it in the Pants repo.
So set up a new dir src/python/internal_backend/
It doesn't get pex'd up with src/python/pants code.
But can be pulled in by adding backends to pants.ini
(e.g., build-support/bin/publish_docs_new.sh creates pants.ini.sitegen by appending a backends to pants.ini)

So far this goal looks for a site description config'd in a json file,
and based on that copies some .html files
(fixing up links between them to be OK in spite of relative-path changes)
and wraps them in a potentially-pretty .html template and stylesheet.
That ain't everything it should do; but it's enough to get an idea of code structure.

To invoke this code,
./build-support/bin/publish_docs_new.sh

Testing Done:
added tests/python/internal_backend_test:: to ci.sh.
https://travis-ci.org/pantsbuild/pants/builds/35997435

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