Documentation for #569

docs/buildingpex.rst

@@ -231,6 +231,14 @@ Even scripts defined by the "scripts" section of a distribution can be used, e.g
                  {bal,hit,hits,new,extend,expire,rm,as,approve,reject,unreject,bonus,notify,give-qual,revoke-qual}
                  ...
     mturk: error: too few arguments
+
+Note: If you run ``pex -c`` and come across an error similar to 
+``pex.pex_builder.InvalidExecutableSpecification: Could not find script 'mainscript.py' in any distribution within PEX!``, 
+double-check your setup.py and ensure that ``mainscript.py`` is included 
+in your setup's ``scripts`` array. If you are using ``console_scripts`` and
+run into this error, double check your ``console_scripts`` syntax - further
+information for both ``scripts`` and ``console_scripts`` can be found in the 
+`Python packaging documentation <https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html>`_.
 
 
 Saving .pex files

docs/index.rst

@@ -31,4 +31,5 @@ Guide:
 
    whatispex
    buildingpex
+   recipes
    api/index

docs/recipes.rst

@@ -0,0 +1,33 @@
+.. _recipes:
+
+PEX Recipes and Notes
+=====================
+
+Gunicorn and PEX
+----------------
+
+Normally, to run a wsgi-compatible application with Gunicorn, you'd just
+point Gunicorn at your application, tell Gunicorn how to run it, and you're
+ready to go - but if your application is shipping as a PEX file, you'll have
+to bundle Gunicorn as a dependency and set Gunicorn as your entry point. Gunicorn
+can't enter a PEX file to retrieve the wsgi instance, but that doesn't prevent
+the PEX from invoking Gunicorn.
+
+This retains the benefit of zero `pip install`'s to run your service, but it
+requires a bit more setup as you must ensure Gunicorn is packaged as a dependency. 
+The following snippets assume Flask as the wsgi framework, Django setup should be 
+similar:
+
+.. code-block:: bash
+
+    $ pex flask gunicorn myapp -c gunicorn -o ~/service.pex
+
+Once your pex file is created, you need to make sure to pass your wsgi app
+instance name to the CLI at runtime for Gunicorn to know how to hook into it,
+configuration can be passed in the same way:
+
+.. code-block:: bash
+
+  $ service.pex myapp:appinstance -c /path/to/gunicorn_config.py
+
+And there you have it, a fully portable python web service.