Radical makeover of docsite.

+ Changes to content: Removed old/outdated/unhelpful content,
  added new content, rephrased various paragraphs to be
  more succinct and/or pertinent to 2016 Pants.

+ Changes to styling, using a customized version of Bootstrap.

I don't think looking at diffs will be particularly instructuve,
since I've made big changes everywhere. It might be better
to look at the content directly:

http://pantsbuild.github.io/staging/_new_design_/

Testing Done:
CI pending: https://travis-ci.org/pantsbuild/pants/builds/125961756

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

.gitattributes

@@ -1,5 +1,6 @@
 *.analysis binary
 *.min.js binary
+*.min.css binary
 *.png binary
 
 src/python/pants/reporting/assets/js/prettify* binary

3rdparty/README.md

@@ -2,4 +2,4 @@
 
 3rdparty dependencies for Pants itself: references to modules whose sources live elsewhere.
 
-If you're looking for references to JVM-based "tool" jars (junit, etc), look in ../BUILD.tools.
+If you're looking for references to JVM-based "tool" jars (junit, etc), look in ../BUILD.tools.

CONTRIBUTING.md

@@ -2,4 +2,4 @@
 
 Pants Developer Center: http://pantsbuild.github.io/dev.html (hacking on Pants itself)
 
-Pants Contributors Guide: http://pantsbuild.github.io/howto_contribute.html (interact with pantsbuild community)
+Pants Contributors Guide: http://pantsbuild.github.io/howto_contribute.html (interact with pantsbuild community)

build-support/README.md

@@ -1,4 +1,4 @@
 /build-support/
 
 Scripts used to build Pants-related things. Scripts, config, and other infrastructure necessary
-for Pants to function.
+for Pants to function.

build-support/bin/publish_docs.sh

@@ -43,6 +43,8 @@ done
 # TODO(benjy): Instead of invoking Pants multiple times, these actions should be chained using
 # products, like everything else.
 
+set -x
+
 ${PANTS_EXE} reference \
   --pants-reference-template=reference/pants_reference_body.html \
   --build-dictionary-template=reference/build_dictionary_body.html \
@@ -71,6 +73,8 @@ ${PANTS_EXE} markdown --fragment \
 ${PANTS_EXE} sitegen --config-path=src/python/pants/docs/docsite.json || \
   die "Failed to generate doc site'."
 
+set +x
+
 do_open "${REPO_ROOT}/dist/docsite/index.html"
 
 if [[ "${publish}" = "true" ]]; then
@@ -86,4 +90,3 @@ continue."
     do_open ${url}/index.html
   ) || die "Publish to ${url} failed."
 fi
-

contrib/scrooge/README.md

@@ -3,4 +3,4 @@ Pants plugins to support the [Scrooge](https://github.com/twitter/scrooge) thrif
 
 Currently there is a code gen plugin for generating java and scala struct and rpc bindings for
 thrift IDLs as well as a thrift-linter plugin for running basic lint checks against thrift IDLs
-that will be used with the scrooge code generator.
+that will be used with the scrooge code generator.

examples/src/java/org/pantsbuild/example/3rdparty_jvm.md

@@ -1,71 +1,32 @@
 JVM 3rdparty Pattern
 ====================
 
-In general, we use the
-[[3rdparty idiom|pants('src/docs:3rdparty')]] to organize
-dependencies on code from outside the source tree. This document
+In general, we recommend the [[3rdparty idiom|pants('src/docs:3rdparty')]]
+for organizing dependencies on code from outside the source tree. This document
 describes how to make this work for JVM (Java or Scala) code.
 
-Your JVM code can pull in code written elsewhere. Pants uses
-[Ivy](http://ant.apache.org/ivy/), a tool based on Maven's jar-sharing.
+Your JVM code can depend on external, third-party libraries. Pants uses
+[Ivy](http://ant.apache.org/ivy/) to resolve and retrieve these JAR files.
 You should know the ([Maven/Ivy groupId, artifactId, and
 version](http://maven.apache.org/guides/mini/guide-central-repository-upload.html))
 you want to use.
 
-The 3rdparty pattern described here eases avoiding diamond dependency
-problems and version conflicts. If your code depends on artifacts `foo`
-and `bar`; and if `foo` and `bar` depend on different versions of the
-`baz` artifact; then some code will be linked together with a version of
-`baz` it didn't "expect." Tracking versioned dependencies in one place
-makes it easier to reason about them.
-
 3rdparty/jvm
 ------------
 
-**The JVM part of 3rdparty is organized by org (Maven groupId).**
-For an example of a repo with 3rdparty arranged this way, see
-[twitter/commons](https://github.com/twitter/commons/tree/master/3rdparty/jvm).
-(Pants' own 3rdparty isn't organized this way; it doesn't have enough 3rdparty
-dependencies for this to make sense.)
-Under there, see if there's already a `3rdparty/jvm/path/to/org/BUILD` file.
-If there isn't, then you want to create one. E.g., to import
-`com.sun.jersey-apache-client`, look in `3rdparty/jvm/com/sun` for a
-likely-looking `BUILD` file--in this example,
-`3rdparty/jvm/com/google/sun/jersey/BUILD`.
-
-In the appropriate `BUILD` file, you want to find a
-<a pantsref="bdict_jar_library">`jar_library`</a>
-with the <a pantsref="bdict_jar">`jar`</a>s you want:
+If you have a small to medium number of third-party dependencies, you can define
+them all in a single `3rdparty/jvm/BUILD` file.  If you have a large number, it
+may make sense to organize them in multiple subdirectories, say by category or by publisher.
+
+In the appropriate `BUILD` file, you create a <a pantsref="bdict_jar_library">`jar_library`</a>
+referencing the <a pantsref="bdict_jar">`jar`</a>s you want:
 
 !inc[start-at=junit&end-before=scalatest](../../../../../../3rdparty/BUILD)
 
-Here, the
-<a pantsref="bdict_jar_library">`jar_library`</a>'s name
-defines a target address that
-other build targets can refer to. The
-<a pantsref="bdict_jar">`jar`</a>s refer to jars known to
-your Ivy resolver.
-
-If there's already a `jar` importing the code you want but with a
-*different* version, then you probably want to talk to other folks in
-your organization to agree on one version. (If there's already a `jar`
-importing the code you want with the version you want, then great. Leave
-it there.)
-
-(You don't *need* a tree of `BUILD` files; you could instead have, e.g., one `3rdparty/jvm/BUILD`
-file. Pants' own repo has its JVM 3rdparty targets in just one `BUILD` file. That works fine because
-Pants doesn't have many 3rdparty JVM dependencies. But as the number of these dependencies grows,
-it makes more sense to set up a directory tree. In a large organization, a tree can ease some
-common tasks. For example, `git log` quickly answers questions like "Who set up this dependency?
-Who cares if I bump the version?")
-
-Additionally, some families of jars have different groupId's but are
-logically part of the same project, or need to have their rev's kept in
-sync. For example, (`com.fasterxml.jackson.core`,
-`com.fasterxml.jackson.dataformat`). Sometimes it makes sense to define
-these in a single build file, such as
-`3rdparty/jvm/com/fasterxml/jackson/BUILD` for the jackson family of
-jars.
+Here, the <a pantsref="bdict_jar_library">`jar_library`</a>'s name
+defines a target address that other build targets can refer to. The
+<a pantsref="bdict_jar">`jar`</a>s refer to jars that Ivy can resolve and fetch.
+
 
 Your Code's BUILD File
 ----------------------
@@ -109,18 +70,9 @@ explicitly when you depend on the binary copy of the *far* dependency:
       ]
     )
 
-Troubleshooting a JVM Dependencies Problem
-------------------------------------------
-
-If you're working in JVM (Java or Scala) and suspect you're pulling in different versions of some
-package, you can dump your dependency "tree" with versions with an Ivy resolve report.
-To generate a report for a target such as the `junit`-using `hello/greet` example tests:
-
-    :::bash
-    $ ./pants resolve.ivy --open examples/tests/java/org/pantsbuild/example/hello/greet
+Controlling JAR Dependency Versions
+-----------------------------------
 
-Ivy's report shows which which package is pulling in the package-version you didn't expect.
-(It might not be clear which version you *want*; but at least you've narrowed down the problem.)
 
 **If you notice a small number of wrong-version things,** then in a JVM
 target, you can depend on a `jar` that specifies a version and sets

examples/src/java/org/pantsbuild/example/BUILD

@@ -4,8 +4,8 @@ page(
   links=[
     ':3rdparty_jvm',
     ':from_maven',
+    ':publish',
     'examples/src/scala/org/pantsbuild/example:readme',
-    'src/docs:publish',
     'src/docs:first_concepts',
     'src/docs:first_tutorial',
   ]
@@ -19,6 +19,11 @@ page(
   ],
 )
 
+page(
+  name='publish',
+  source='publish.md',
+)
+
 page(
   name='3rdparty_jvm',
   source='3rdparty_jvm.md',

examples/src/java/org/pantsbuild/example/from_maven.md

@@ -14,24 +14,21 @@ Maven, Pants targets might feel familiar. (If you're converting Maven
 `pom.xml`s to `BUILD` files, <a pantsref="setup_mvn2pants">some scripts written by others who
 have done the same</a> can give you a head start.)
 Both Maven and Pants expect code to be laid out in directories in a consistent way. If you're used
-to Maven's commands, many of Pants' goals will feel eerily familiar.
+to Maven's commands, many of Pants' goals will feel familiar.
 
 Pants uses Ivy to manage artifact fetching and publishing; Ivy's
 behavior here is pretty similar to Maven.
 
 Three Pants features that especially confuse Maven experts as they move
-to pants are
+to pants are:
 
 -   Pants has a first-class mechanism for targets depending on other
     targets on the local file system
 -   Pants targets do not specify version numbers; versions are only
     determined during release
--   BUILD files are python code that pants evaluates dynamically.
 
-The first two points are a significant departure from Maven's handling
-of inter-project dependencies. The last point isn't necessary for
-understanding how to read and write most BUILD files, but is helpful to
-be aware of.
+These points are a significant departure from Maven's handling
+of inter-project dependencies.
 
 Folks switching a Maven-built codebase to Pants often encounter another
 source of confusion: they uncover lurking jar-dependency version
@@ -49,32 +46,14 @@ for advice.
 Pants Equivalents
 -----------------
 
-`exec:java` run a binary<br>
-`run`
+**Run a binary**<br>
+Maven: `exec:java`<br>
+Pants: `run`
 
-`-Xdebug` run a binary in the debugger<br>
-`run.jvm --jvm-debug`
-
-`-Dtest=com.foo.BarSpec -Dmaven.surefire.debug=true test` run one test in the debugger<br>
-`test.junit --jvm-debug --test=com.foo.BarSpec`
-
-Depending on Source, not Jars
------------------------------
-
-Pants arose in an environment of a big multi-project repo. Several teams
-contributed code to the same source tree; projects depended on each
-other. Getting those dependencies to work with Maven was tricky. As the
-number of engineers grew, it wasn't so easy to have one team ask another
-team to release a new jar. Using snapshot dependencies mostly worked,
-but it wasn't always clear what needed rebuilding when pulling fresh
-code from origin; if you weren't sure and didn't want to investigate,
-the safe thing was to rebuild everything your project depended upon.
-Alas, for a big tree of Scala code, that might take 45 minutes.
-
-Pants has a first-class concept of "depend on whatever version of this
-project is defined on disk," and caches targets based on their
-fingerprints (i.e. SHAs of the contents of the files and command line
-options used to build the target). When code changes (e.g., after a git
-pull), pants recompiles only those targets whose source files have
-differing contents.
+**Run a binary in the debugger**<br>
+Maven: `-Xdebug`<br>
+Pants: `run.jvm --jvm-debug`
 
+**Run one test in the debugger**<br>
+Maven: `-Dtest=com.foo.BarSpec -Dmaven.surefire.debug=true test`<br>
+Pants: `test.junit --jvm-debug --test=com.foo.BarSpec`

examples/src/java/org/pantsbuild/example/page.md

@@ -1,11 +1,8 @@
-README Files and Markdown
-=========================
-
-You can write program documentation in the popular Markdown or ReST format;
-Pants eases publishing your docs to places where your users can read it.
-E.g., that `README.md` file in your source code is handy for editing;
-but you might want to generate a web page from that so folks can decide
-whether they want to look at your source code.
+Markdown
+========
+
+You can write codebase documentation in the popular Markdown or ReST format;
+Pants eases generating readable versions and publishing them so your users can read it.
 
 Markdown to HTML
 ----------------