Update install guide to use ./pants generate-pants-ini and `pants_r…

…untime_python_version` (pantsbuild#7453)

Now that we support running with Python 3 and have the `./pants generate-pants-ini` command, we must update our setup instructions to explain how to use both.

README.md

@@ -18,15 +18,15 @@ We use [Coveralls](https://coveralls.io) to monitor test coverage
 
 # Requirements
 
-At a minimum, pants requires the following to run properly:
+At a minimum, Pants requires the following to run properly:
 
-* Linux or Mac OS X
-* Python 2.7.x (the latest stable version of 2.7 is recommended)
+* Linux or macOS.
+* Python 2.7 or 3.6.
 * A C compiler, system headers, Python headers (to compile native Python modules) and the libffi
   library and headers (to compile and link modules that use CFFI to access native code).
-* Internet access (so that pants can fully bootstrap itself)
+* Internet access (so that Pants can fully bootstrap itself)
 
-Additionally, if you use the jvm backend to work with java or scala code (installed by default):
+Additionally, if you use the JVM backend to work with Java or Scala code (installed by default):
 
-* OpenJDK or Oracle JDK version 7 or greater
+* OpenJDK or Oracle JDK version 7 or greater.
 

src/docs/howto_develop.md

@@ -84,9 +84,10 @@ You'll need to setup some files one-time in your own repo:
         'linux-x86_64',
         'macosx-10.4-x86_64',
       ],
-      # You may want to adjust the python interpreter constraints, but note that pants requires
-      # python2.7 currently.
-      compatibility='CPython>=2.7,<3',
+      # You may want to adjust the Python interpreter constraints. Note that Pants requires Python 2.7
+      # or 3.6+. Pex currently does not support flexible interpreter constraints (tracked by
+      # https://github.com/pantsbuild/pex/issues/690), so you must choose which version to target.
+      compatibility=['CPython==3.6.*'],
       dependencies=[
         ':pantsbuild.pants',
         # List any other pants backend local or remote deps here, ie:
@@ -324,4 +325,3 @@ present as follows:
             ...
           </chain>
         </resolvers>
-

src/docs/install.md

@@ -1,63 +1,51 @@
 Installing Pants
 ================
 
-There are a few ways to get a runnable version of pants set up for your workspace. Before
-beginning, make sure your machine fits the requirements. At a minimum, pants requires the following to run properly:
+There are a few ways to get a runnable version of Pants set up for your workspace. Before
+beginning, make sure your machine fits the requirements. At a minimum, Pants requires the following to run properly:
 
-* Linux or Mac OS X.
-* Python 2.7.x (the latest stable version of 2.7 is recommended).
+* Linux or macOS.
+* Python 2.7 or 3.6.
 * A C compiler, system headers, Python headers (to compile native Python modules) and the libffi
   library and headers (to compile and link modules that use CFFI to access native code).
 * OpenJDK or Oracle JDK 7 or greater.
-* Internet access (so that pants can fully bootstrap itself)
+* Internet access (so that Pants can fully bootstrap itself)
 
-After you have pants installed, you'll need to
+After you have Pants installed, you'll need to
 [[Set up your code workspace to work with Pants|pants('src/docs:setup_repo')]].
 
 Recommended Installation
 ------------------------
 
-To set up pants in your repo, we recommend installing our self-contained `pants` bash script
-in the root (ie, "buildroot") of your repo:
+To set up Pants in your repo, we recommend installing our self-contained `pants` bash script
+in the root (i.e. the "buildroot") of your repo:
 
     :::bash
-    curl -L -O https://pantsbuild.github.io/setup/pants && chmod +x pants && touch pants.ini
+    curl -L -O https://pantsbuild.github.io/setup/pants && chmod +x pants
 
-The first time you run the new `./pants` script it will install the latest version of pants (using
-virtualenv) and then run it.  It's recommended though, that you pin the version of pants.  To do
-this, first find out the version of pants you just installed:
+Start by running the below command to auto-generate a `pants.ini` config file with sensible defaults.
 
     :::bash
-    ./pants -V
-    1.0.0
+    ./pants generate-pants-ini
 
-Then add an entry like so to `pants.ini` with that version:
+This command pins the `pants_version`. When you'd like to upgrade Pants, just edit the version in `pants.ini` and `./pants` will self-update on the next run.
 
-    :::ini
-    [GLOBAL]
-    pants_version: 1.0.0
-
-When you'd like to upgrade pants, just edit the version in `pants.ini` and pants will self-update on
-the next run.  This script stores the various pants versions you use centrally in
-`~/.cache/pants/setup`.  When you switch back and forth between branches pants will select the
-correct version from your local cache and use that.
-
-If you use pants plugins published to pypi you can configure them by adding a `plugins` list as
-follows:
+To use Pants plugins published to PyPi, add them to a `plugins` list, like so:
 
     :::ini
     [GLOBAL]
-    pants_version: 1.0.0
+    pants_version: 1.15.0
 
     plugins: [
         'pantsbuild.pants.contrib.go==%(pants_version)s',
         'pantsbuild.pants.contrib.scrooge==%(pants_version)s',
       ]
 
-Pants notices you changed your plugins and it installs them.
-NB: The formatting of the plugins list is important; all lines below the `plugins:` line must be
-indented by at least one white space to form logical continuation lines. This is standard for python
-ini files, see [[Options|pants('src/docs:options')]].
+Pants will notice you changed your plugins and will install them the next time you run `./pants`.
+
+Note that the formatting of the plugins list is important; all lines below the `plugins:` line must be
+indented by at least one white space to form logical continuation lines. This is standard for Python
+ini files. See [[Options|pants('src/docs:options')]] for a guide on modifying your `pants.ini`.
 
 The ./pants Runner Script
 -------------------------
@@ -98,6 +86,6 @@ where you are attempting to bootstrap pants. In particular, if you see an error
     Failed to install requirements from /Users/someuser/workspace/pants/3rdparty/python/requirements.txt.
 
 This indicates that pants was attempting to `pip install` the `psutil` dependency into it's private
-virtualenv, and that install failed due to a compiler issue. On Mac OS X, we recommend running
+virtualenv, and that install failed due to a compiler issue. On macOS, we recommend running
 `xcode-select --install` to make sure you have the latest compiler infrastructure installed, and
 unset any compiler-related environment variables (i.e. run `unset CC`).