Merge branch 'master' into wickman/1.0

README.rst

@@ -45,45 +45,62 @@ possible and is more in-line with what pex does philosophically.
 Simple Examples
 ===============
 
-Launch an interpreter with ``requests`` and ``flask`` in the environment:
+Launch an interpreter with ``requests``, ``flask`` and ``psutil`` in the environment:
 
 .. code-block:: bash
 
-    $ pex requests flask
+    $ pex requests flask 'psutil>2,<3'
 
-Or instead launch an interpreter with the requirements from requirements.txt:
+Or instead freeze your current virtualenv via requirements.txt and execute it anywhere:
 
 .. code-block:: bash
 
-    $ pex -r requirements.txt
+    $ pex -r <(pip freeze) -o my_virtualenv.pex
+    $ deactivate
+    $ ./my_virtualenv.pex
 
-Run webserver.py in an environment containing ``flask`` and the setup.py package in
-the current working directory:
+Run webserver.py in an environment containing ``flask`` as a quick way to experiment:
 
-.. code-block::
+.. code-block:: bash
 
-    $ pex flask -s . -- webserver.py
+    $ pex flask -- webserver.py
 
 Launch Sphinx in an ephemeral pex environment using the Sphinx entry point ``sphinx:main``:
 
 .. code-block:: bash
 
     $ pex sphinx -e sphinx:main -- --help
 
-Build a standalone pex binary into ``pex.pex``:
+Build a standalone pex binary into ``pex.pex`` using the ``pex`` console_scripts entry point:
 
-.. code-block::
+.. code-block:: bash
 
-    $ pex pex -e pex.bin.pex:main -o pex.pex
+    $ pex pex -c pex -o pex.pex
 
-Build a standalone pex binary but invoked using a specific Python version:
+You can also build pex files that use a specific interpreter type:
 
-.. code-block::
+.. code-block:: bash
 
-    $ pex pex -e pex.bin.pex:main --python=pypy -o pypy-pex.pex
+    $ pex pex -c pex --python=pypy -o pypy-pex.pex
 
 Most pex options compose well with one another, so the above commands can be
-mixed and matched.
+mixed and matched.  For a full list of options, just type ``pex --help``.
+
+
+Integrating pex into your workflow
+==================================
+
+If you use tox (and you should!), a simple way to integrate pex into your
+workflow is to add a packaging test environment to your ``tox.ini``:
+
+.. code-block:: ini
+
+    [testenv:package]
+    deps = pex
+    commands = pex . -o dist/app.pex
+
+Then ``tox -e package`` will produce a relocateable copy of your application
+that you can copy to staging or production environments.
 
 
 Documentation
@@ -103,29 +120,11 @@ the test suite, just invoke tox:
 
     $ tox
 
-To generate a coverage report (with more substantial integration tests):
-
-.. code-block:: bash
-
-   $ tox -e coverage
-
-To check style and sort ordering:
-
-.. code-block:: bash
-
-   $ tox -e style,isort-check
-
-To generate and open local sphinx documentation:
+If you don't have tox, you can generate a pex of tox:
 
-.. code-block:: bash
-
-   $ tox -e docs
-
-To run the 'pex' tool from source (for 3.4, use 'py34-run'):
-
-.. code-block:: bash
+.. code-block::
 
-   $ tox -e py27-run -- <cmdline>
+    $ pex tox -c tox -o ~/bin/tox
 
 
 Contributing

docs/api/index.rst

@@ -1,8 +1,159 @@
 PEX API Reference
 =================
 
-.. toctree::
-    :maxdepth: 2
+Module contents
+---------------
 
-    pex
-    pex.bin
+.. automodule:: pex
+    :members:
+    :show-inheritance:
+
+pex.crawler module
+------------------------
+
+.. automodule:: pex.crawler
+    :members:
+    :show-inheritance:
+
+pex.environment module
+----------------------
+
+.. automodule:: pex.environment
+    :members:
+    :show-inheritance:
+
+pex.fetcher module
+------------------
+
+.. automodule:: pex.fetcher
+    :members:
+    :show-inheritance:
+
+pex.finders module
+------------------
+
+.. automodule:: pex.finders
+    :members:
+    :show-inheritance:
+
+pex.http module
+--------------------
+
+.. automodule:: pex.http
+    :members:
+    :show-inheritance:
+
+pex.installer module
+--------------------
+
+.. automodule:: pex.installer
+    :members:
+    :show-inheritance:
+
+pex.interpreter module
+----------------------
+
+.. automodule:: pex.interpreter
+    :members:
+    :show-inheritance:
+
+pex.iterator module
+----------------------
+
+.. automodule:: pex.iterator
+    :members:
+    :show-inheritance:
+
+pex.link module
+----------------------
+
+.. automodule:: pex.link
+    :members:
+    :show-inheritance:
+
+pex.package module
+------------------
+
+.. automodule:: pex.package
+    :members:
+    :show-inheritance:
+
+pex.pep425 module
+-----------------
+
+.. automodule:: pex.pep425
+    :members:
+    :show-inheritance:
+
+pex.pex module
+--------------
+
+.. automodule:: pex.pex
+    :members:
+    :show-inheritance:
+
+pex.pex_builder module
+----------------------
+
+.. automodule:: pex.pex_builder
+    :members:
+    :show-inheritance:
+
+pex.pex_info module
+-------------------
+
+.. automodule:: pex.pex_info
+    :members:
+    :show-inheritance:
+
+pex.platforms module
+--------------------
+
+.. automodule:: pex.platforms
+    :members:
+    :show-inheritance:
+
+pex.resolver module
+-------------------
+
+.. automodule:: pex.resolver
+    :members:
+    :show-inheritance:
+
+pex.testing module
+------------------
+
+.. automodule:: pex.testing
+    :members:
+    :show-inheritance:
+
+pex.tracer module
+-----------------
+
+.. automodule:: pex.tracer
+    :members:
+    :show-inheritance:
+
+pex.translator module
+---------------------
+
+.. automodule:: pex.translator
+    :members:
+    :show-inheritance:
+
+pex.util module
+---------------
+
+.. automodule:: pex.util
+    :members:
+    :show-inheritance:
+
+
+pex.variables module
+--------------------
+
+.. _PexVariables:
+
+.. automodule:: pex.variables
+    :members:
+    :show-inheritance: