Add Pyramid tutorial using virtualenv and pyramid_rpc.

Fixes: #841

Author: thijstriemstra

doc/tutorials/examples/gateways/pylons/pyramid_client.py

@@ -7,7 +7,7 @@
 
 from pyamf.remoting.client import RemotingService
 
-url = 'http://127.0.0.1:8080/gateway'
+url = 'http://127.0.0.1:6543/gateway'
 client = RemotingService(url, logger=logging)
 service = client.getService('myservice')
 echo = service.echo('Hello World!')

doc/tutorials/examples/gateways/pylons/pyramid_gateway.py

@@ -1,10 +1,8 @@
-import logging
-
-from pyramid.config import Configurator
 from pyramid_rpc.amfgateway import PyramidGateway
 
-from paste.httpserver import serve
 
+def my_view(request):
+    return {'project':'pyamf_tutorial'}
 
 def echo(request, data):
     """
@@ -19,11 +17,5 @@ def echo(request, data):
     # Add other exposed functions and classes here
 }
 
-echoGateway = PyramidGateway(services, logger=logging, debug=True)
-
+echoGateway = PyramidGateway(services, debug=True)
 
-if __name__ == '__main__':
-    config = Configurator()
-    config.add_view(echoGateway, name='gateway')
-    app = config.make_wsgi_app()
-    serve(app, host='0.0.0.0')

doc/tutorials/gateways/images/pylons-logo.png

@@ -2,14 +2,16 @@
   Pylons Project
 ******************
 
+.. image:: images/pylons-logo.png
+
 .. topic:: Introduction
 
    The `Pylons Project`_ is a collection of web application framework
    technologies. This tutorial describes how to setup a bare bones
    application with a remoting gateway exposing a method.
 
-   **Note**: This tutorial provides examples for both Pyramid_ and the old
-   `Pylons package`_ (versions 0.97-1.x). For new projects it is recommended
+   **Note**: This tutorial provides examples for both Pyramid_ and the legacy
+   `Pylons package`_ (versions 0.97-1.x). For new projects it is encouraged
    to use the Pyramid package, see the `Pylons FAQ`_ for more information. 
 
 
@@ -19,49 +21,98 @@
 Pyramid
 =======
 
-The Pyramid_ package supports extensibility through add-ons. For this tutorial
-we need RPC support for AMF_ which is available in the `pyramid_rpc`_ add-on.
+Pyramid_ is a small, fast, down-to-earth Python web application development
+framework. It is developed as part of the `Pylons Project`_.
 
-Install_ the ``pyramid_rpc`` package:
+Example
+-------
+
+1. Create a new virtual environment using the virtualenv_ tool:
 
   .. code-block:: bash
 
-     $ easy_install pyramid_rpc
+     $ virtualenv --no-site-packages pyramid_amf_env
 
 
-Example
--------
+2. The Pyramid_ package supports extensibility through add-ons. For this tutorial
+   we need AMF support which is available in the `pyramid_rpc`_ add-on.
+
+  Install the ``pyramid``, ``pyramid_rpc`` and ``pyamf`` packages:
+
+  .. code-block:: bash
+
+     $ cd pyramid_amf_env
+     $ bin/easy_install pyramid pyramid_rpc pyamf
 
-1. Create a new Python script called ``server.py`` with the following:
+
+  For more detailed instructions, refer to the Pyramid `installation documentation`_.
+
+
+3. Create a new Pyramid project (called ``pyamf_tutorial`` in this example):
+
+  .. code-block:: bash
+
+     $ bin/paster create -t pyramid_starter pyamf_tutorial
+
+
+4. Install the project into the enviroment:
+
+  .. code-block:: bash
+
+     $ cd pyamf_tutorial
+     $ ../bin/python setup.py develop
+
+
+5. Replace the contents of ``pyamf_tutorial/views.py`` with the following:
 
   .. literalinclude:: ../examples/gateways/pylons/pyramid_gateway.py
      :linenos:
 
   You can easily expose more functions by adding them to the ``services`` dictionary
-  given to ``PyramidGateway``.
+  given to ``PyramidGateway``. Also see the `pyramid_rpc documentation`_.
+
+
+6. Add the view to the routing map, open ``pyamf_tutorial/__init__.py`` and look for the line:
 
+  .. code-block:: python
+
+     config.add_static_view('static', 'pyamf_tutorial:static')
+
+  Just above that line, configure the route to the view you created earlier.
 
-2. Fire up the web server with:
+  .. code-block:: python
+  
+     config.add_view('pyamf_tutorial.views.echoGateway', name='gateway')
+
+
+7. Fire up the web server with:
 
   .. code-block:: bash
 
-     $ python server.py
+     $ ../bin/paster serve development.ini
 
   That should print something like:
 
   .. code-block:: bash
 
-     serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
+     Starting server in PID 16601.
+     serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
 
 
-3. To test the gateway you can use a Python AMF client like this:
+8. To test the gateway you can use a Python AMF client like this:
 
   .. literalinclude:: ../examples/gateways/pylons/pyramid_client.py
      :linenos:
 
 
-Pylons
-======
+
+Pylons (0.97-1.x)
+=================
+
+This section of the tutorial covers the legacy `Pylons package`_.
+
+Example
+-------
 
 1. Create a new Pylons project with:
 
@@ -141,5 +192,6 @@ Pylons
 .. _Pylons package: http://docs.pylonsproject.org/docs/pylons.html
 .. _pyramid_rpc: http://docs.pylonsproject.org/projects/pyramid_rpc/dev/
 .. _Pylons FAQ: http://docs.pylonsproject.org/faq/pylonsproject.html
-.. _AMF: http://docs.pylonsproject.org/projects/pyramid_rpc/dev/amf.html
-.. _Install: http://docs.pylonsproject.org/projects/pyramid_rpc/dev/#installation
+.. _pyramid_rpc documentation: http://docs.pylonsproject.org/projects/pyramid_rpc/dev/amf.html
+.. _virtualenv: http://pypi.python.org/pypi/virtualenv
+.. _installation documentation: http://docs.pylonsproject.org/projects/pyramid/1.1/narr/install.html#installing-chapter