Improve the examples in the tutorial.

3 files changed, 95 insertions, 19 deletions

diff --git a/sphinx/source/tutorial/basics.rst b/sphinx/source/tutorial/basics.rst
index f4afc116..c4f2a100 100644
--- a/sphinx/source/tutorial/basics.rst
+++ b/sphinx/source/tutorial/basics.rst
@@ -7,6 +7,7 @@ when written using CherryPy::
 
     import cherrypy
 
+
     class HelloWorld:
         def index(self):
             return "Hello world!"
@@ -43,7 +44,8 @@ Let's take a look at ``hello.py``:
    ``index()`` method will be **exposed**. Only exposed methods can be called
    to answer a request. This feature allows the user to select which methods
    of an object will be accessible via the Web; non-exposed methods can't be
-   accessed.
+   accessed. Another way to **expose** a method is to use the decorator
+   :func:`cherrypy.expose`.
  * ``cherrypy.quickstart(HelloWorld())`` mounts an instance of the HelloWorld
    class, and starts the embedded webserver. It runs until explicitly
    interrupted, either with ``Ctrl-C`` or via a suitable signal (a simple
@@ -115,14 +117,30 @@ headers (to be returned in the response) in the `headers` attribute of
 
 For example, to find out what "host" to which the client intended to connect::
 
-    @cherrypy.expose
-    def index(self):
-        host = cherrypy.request.headers('Host')
-        return "You have successfully reached " + host
+    import cherrypy
+
+
+    class HelloWorld:    
+        @cherrypy.expose
+        def index(self):
+            host = cherrypy.request.headers('Host')
+            return "You have successfully reached " + host
+
+    cherrypy.quickstart(HelloWorld())
 
 Or to set headers on the response::
 
-    @cherrypy.expose
-    def index(self):
-        cherrypy.response.headers['Content-Type'] = 'application/jpeg'
-        return my_jpeg_data()
+    import cherrypy
+
+
+    class HelloWorld:    
+        def _get_jpeg_data(self):
+	    """This method should return the jpeg data"""
+	    return ""
+    
+        @cherrypy.expose
+        def index(self):
+            cherrypy.response.headers['Content-Type'] = 'application/jpeg'
+            return self._get_jpeg_data()
+
+    cherrypy.quickstart(HelloWorld())
diff --git a/sphinx/source/tutorial/dispatching.rst b/sphinx/source/tutorial/dispatching.rst
index bc83f476..20da69ae 100644
--- a/sphinx/source/tutorial/dispatching.rst
+++ b/sphinx/source/tutorial/dispatching.rst
@@ -92,11 +92,15 @@ In this example, the URL ``http://localhost/some/page`` will be mapped to the
 In our HelloWorld example, adding the ``http://localhost/onepage/`` mapping
 to ``OnePage().index`` could be done like this::
 
+    import cherrypy
+
+
     class OnePage(object):
         def index(self):
             return "one page!"
         index.exposed = True
 
+
     class HelloWorld(object):
         onepage = OnePage()
 
@@ -114,11 +118,29 @@ Normal methods
 CherryPy can directly call methods on the mounted objects, if it receives a
 URL that is directly mapped to them. For example::
 
-    def foo(self):
+
+    """This example can handle the URIs
+    /    -> OnePage.index
+    /foo -> OnePage.foo -> foo
+    """
+    import cherrypy
+
+
+    class OnePage(object):
+        def index(self):
+            return "one page!"
+        index.exposed = True
+
+
+    def foo():
         return 'Foo!'
     foo.exposed = True
 
-    root.foo = foo
+    if __name__ == '__main__':
+        root = OnePage()
+	root.foo = foo
+        cherrypy.quickstart(root)
+
 
 In the example, ``root.foo`` contains a function object, named ``foo``. When
 CherryPy receives a request for the ``/foo`` URL, it will automatically call
@@ -175,8 +197,7 @@ The following code can be used to handle this URL::
 
     class Root:
         def doLogin(self, username=None, password=None):
-            # check the username & password
-            ...
+            """Check the username & password"""
         doLogin.exposed = True
 
 Both arguments have to be declared as *keyword arguments*. The default value
@@ -214,7 +235,8 @@ following code::
 
     class Root:
         def blog(self, year, month, day):
-            ...
+	    """Deliver the blog post. According to *year* *month* *day*.
+	    """
         blog.exposed = True
 
     root = Root()
@@ -246,10 +268,14 @@ written the above "blog" example equivalently with a "default" method instead::
 
     class Blog:
         def default(self, year, month, day):
-            ...
+            """This method catch the positional arguments 
+             *year*,*month*,*day* to delivery the blog content.
+            """
         default.exposed = True
 
-    class Root: pass
+
+    class Root:
+        pass
 
     root = Root()
     root.blog = Blog()
diff --git a/sphinx/source/tutorial/exposing.rst b/sphinx/source/tutorial/exposing.rst
index bab4c67a..c982d000 100644
--- a/sphinx/source/tutorial/exposing.rst
+++ b/sphinx/source/tutorial/exposing.rst
@@ -20,15 +20,16 @@ this case, one can directly set the exposed attribute::
 
     class Root:
         def index(self):
-            ...
+	    """Handle the / URI"""
         index.exposed = True
 
 
 or use a decorator::
 
+    class Root:
         @cherrypy.expose
         def index(self):
-            ...
+	    """Handle the / URI"""
 
 
 When it is a special method, such as ``__call__``, that is to be invoked,
@@ -37,6 +38,37 @@ the exposed attribute must be set on the class itself::
     class Node:
         exposed = True
         def __call__(self):
-            ...
+            """ """
+
+The technics can be mixed, for example::
+
+    """This example can handle the URIs:
+    /       ->  Root.index
+    /page   ->  Root.page
+    /node   ->  Node.__call__
+    """
+    import cherrypy
+
+
+    class Node(object):
+        exposed = True
+    
+        def __call__(self):
+	    return "The node content"
+
+
+    class Root:
+        node = Node()
+
+        @cherrypy.expose       
+        def index(self):
+            return "The index of the root object"
 
+        def page(self):
+            return 'This is the "page" content'
+        page.exposed = True
+    
 
+    if __name__ == '__main__':
+        cherrypy.quickstart(Root())
+