Documentation fixes ported from 0.8.1.

5 files changed, 127 insertions, 17 deletions

diff --git a/apidoc/changelog.rst b/apidoc/changelog.rst
index 7c7344a..b6715b8 100644
--- a/apidoc/changelog.rst
+++ b/apidoc/changelog.rst
@@ -5,12 +5,11 @@
 Release Notes and Changelog
 ===========================
 
-Release 0.7
+Release 0.8
 ===========
 
 .. rubric:: API changes 
 
-
 These changes may break compatibility with previous versions.
 
 * The built-in Key/Value database is not available anymore. It is marked deprecated since 0.6.4
@@ -18,9 +17,8 @@ These changes may break compatibility with previous versions.
 
   * Regular expressions must be encapsulated with ``#``. In 0.6 all non-alphanumeric characters not present in the regular expression were allowed.
   * Regular expressions not part of a route wildcard are escaped automatically. You don't have to escape dots or other regular control characters anymore. In 0.6 the whole URL was interpreted as a regular expression. You can use anonymous wildcards (``/index:#(\.html)?#``) to achieve a similar behaviour.
-  * Wildcards are escaped with a second colon (``/path/::not_a_wildcard``).
 
-* The ``BreakTheBottle`` exception is gone. Use :class:`HTTPResponse`` instead.
+* The ``BreakTheBottle`` exception is gone. Use :class:`HTTPResponse` instead.
 * The :class:`SimpleTemplate` engine escapes HTML special characters in ``{{bad_html}}`` expressions automatically. Use the new ``{{!good_html}}`` syntax to get old behaviour (no escaping).
 * The :class:`SimpleTemplate` engine returns unicode strings instead of lists of byte strings.
 * ``bottle.optimize()`` and the automatic route optimization is obsolete.
diff --git a/apidoc/faq.rst b/apidoc/faq.rst
index b57a775..893e1d1 100644
--- a/apidoc/faq.rst
+++ b/apidoc/faq.rst
@@ -32,10 +32,6 @@ Bottle searches in ``./`` and ``./views/`` for templates. In a mod_python_ or mo
 
     bottle.TEMPLATE_PATH.insert(0,'/absolut/path/to/templates/')
 
-or change the working directory::
-
-    os.chdir(os.path.dirname(__file__))
-
 so bottle searches the right paths.
 
 Dynamic Routes and Slashes
diff --git a/apidoc/index.rst b/apidoc/index.rst
index ae62f69..2ed011e 100755
--- a/apidoc/index.rst
+++ b/apidoc/index.rst
@@ -26,7 +26,7 @@ Bottle is a fast, simple and lightweight WSGI_ micro web-framework for Python_.
 * **Routing:** Requests to function-call mapping with support for clean and  dynamic URLs.
 * **Templates:** Fast and pythonic :ref:`build-in template engine <tutorial-templates>` and support for mako_, jinja2_ and cheetah_ templates.
 * **Utilities:** Convenient access to form data, file uploads, cookies, headers and other HTTP related metadata.
-* **Server:** Build-in HTTP development server and support for paste_, fapws3_, flup_, cherrypy_ or any other WSGI_ capable HTTP server.
+* **Server:** Build-in HTTP development server and support for paste_, fapws3_, `Google App Engine <http://code.google.com/intl/en-US/appengine/>`_, cherrypy_ or any other WSGI_ capable HTTP server.
 
 .. rubric:: Example: "Hello World" in a bottle
 
@@ -48,20 +48,25 @@ Bottle is a fast, simple and lightweight WSGI_ micro web-framework for Python_.
 
 Install the latest stable release via PyPi_ (``easy_install -U bottle``) or download `bottle.py`__ (unstable) into your project directory. There are no hard [1]_ dependencies other than the Python standard library. Bottle runs with **Python 2.5+ and 3.x** (using 2to3)
 
-Documentation
+User's Guide
 ===============
-The documentation is a work in progress. If you have questions not answered here, please check the :doc:`faq`, file a ticket at bottles issue_tracker_ or send an e-mail to the `mailing list <mailto:bottlepy@googlegroups.com>`_.
+Start here if you want to learn how to use the bottle framework for web development. If you have any questions not answered here, feel free to ask the `mailing list <mailto:bottlepy@googlegroups.com>`_.
 
 .. toctree::
    :maxdepth: 2
 
    tutorial
-   recieps
+   stpl
    faq
+
+API Documentation
+==================
+Looking for a specific function, class or method? These chapters cover all the interfaces provided by the Framework and explain how to use them.
+
+.. toctree::
+   :maxdepth: 2
+
    api
-   stpl
-   changelog
-   development
 
 Tutorials and Resources
 =======================
@@ -70,7 +75,18 @@ Tutorials and Resources
    :maxdepth: 2
 
    tutorial_app
+   recieps
+
+Development and Contribution
+============================
+
+These chapters are intended for developers interested in the bottle development and release workflow.
 
+.. toctree::
+   :maxdepth: 2
+
+   changelog
+   development
 
 
 Licence
diff --git a/apidoc/recieps.rst b/apidoc/recieps.rst
new file mode 100644
index 0000000..93fbf6f
--- /dev/null
+++ b/apidoc/recieps.rst
@@ -0,0 +1,99 @@
+.. module:: bottle
+
+.. _beaker: http://beaker.groovie.org/
+.. _mod_python: http://www.modpython.org/
+.. _mod_wsgi: http://code.google.com/p/modwsgi/
+.. _werkzeug: http://werkzeug.pocoo.org/documentation/dev/debug.html
+.. _paste: http://pythonpaste.org/modules/evalexception.html
+.. _pylons: http://pylonshq.com/
+
+Recieps
+=============
+
+This is a collection of code snippets and examples for common use cases. 
+
+Keeping track of Sessions
+----------------------------
+
+There is no build in support for sessions because there is no *right* way to do it (in a micro framework). Depending on requirements and environment you could use beaker_ middleware with a fitting backend or implement it yourself. Here is an example for beaker sessions with a file-based backend::
+
+    import bottle
+    from beaker.middleware import SessionMiddleware
+
+    session_opts = {
+        'session.type': 'file',
+        'session.cookie_expires': 300,
+        'session.data_dir': './data',
+        'session.auto': True
+    }
+    app = SessionMiddleware(bottle.app(), session_opts)
+
+    @bottle.route('/test')
+    def test():
+      s = bottle.request.environ.get('beaker.session')
+      s['test'] = s.get('test',0) + 1
+      s.save()
+      return 'Test counter: %d' % s['test']
+
+    bottle.run(app=app)
+
+Debugging with Style: Debugging Middleware
+--------------------------------------------------------------------------------
+
+Bottle catches all Exceptions raised in your app code to prevent your WSGI server from crashing. If the build-in :func:`debug` mode is not enough and you need exceptions to propagate to a debugging middleware, you can turn off this behaviour::
+
+    import bottle
+    app = bottle.app() 
+    app.catchall = False #Now most exceptions are re-raised within bottle.
+    myapp = DebuggingMiddleware(app) #Replace this with a middleware of your choice (see below)
+    bottle.run(app=myapp)
+
+Now, bottle only catches its own exceptions (:exc:`HTTPError`, :exc:`HTTPResponse` and :exc:`BottleException`) and your middleware can handle the rest.
+
+The werkzeug_ and paste_ libraries both ship with very powerfull debugging WSGI middleware. Look at :class:`werkzeug.debug.DebuggedApplication` for werkzeug_ and :class:`paste.evalexception.middleware.EvalException` for paste_. They both allow you do inspect the stack and even execute python code within the stack context, so **do not use them in production**.
+
+
+Embedding other WSGI Apps
+--------------------------------------------------------------------------------
+
+This is not the recommend way (you should use a middleware in front of bottle to do this) but you can call other WSGI applications from within your bottle app and let bottle act as a pseudo-middleware. Here is an example::
+
+    from bottle import request, response, route
+    subproject = SomeWSGIApplication()
+
+    @route('/subproject/:subpath#.*#', method='ALL')
+    def call_wsgi(subpath):
+        new_environ = request.environ.copy()
+        new_environ['SCRIPT_NAME'] = new_environ.get('SCRIPT_NAME','') + '/subproject'
+        new_environ['PATH_INFO'] = '/' + subpath
+        def start_response(status, headerlist):
+            response.status = int(status.split()[0])
+            for key, value in headerlist:
+                response.add_header(key, value)
+      return app(new_environ, start_response)
+
+Again, this is not the recommend way to implement subprojects. It is only here because many people asked for this and to show how bottle maps to WSGI.
+
+
+Ignore tailing slashes
+--------------------------------------------------------------------------------
+
+For Bottle, ``/example`` and ``/example/`` are two different routes. To threat both URLs the same you can add two ``@route`` decorators::
+
+    @route('/test')
+    @route('/test/')
+    def test(): return 'Slash? no?'
+
+or add a WSGI middleware that strips tailing slashes from all URLs::
+
+    class StripPathMiddleware(object):
+      def __init__(self, app):
+        self.app = app
+      def __call__(self, e, h):
+        e['PATH_INFO'] = e['PATH_INFO'].rstrip('/')
+        return self.app(e,h)
+    
+    app = bottle.app()
+    myapp = StripPathMiddleware(app)
+    bottle.run(app=appmy)
+
diff --git a/bottle.py b/bottle.py
index e1acc8e..5384740 100755
--- a/bottle.py
+++ b/bottle.py
@@ -1004,7 +1004,7 @@ def redirect(url, code=303):
 
 
 def send_file(*a, **k): #BC 0.6.4
-    """ Raises the output of static_file() """
+    """ Raises the output of static_file(). (deprecated) """
     raise static_file(*a, **k)
 
 
@@ -1196,7 +1196,8 @@ url    = functools.wraps(Bottle.get_url)(lambda *a, **ka: app().get_url(*a, **ka
 mount  = functools.wraps(Bottle.get_url)(lambda *a, **ka: app().mount(*a, **ka))
 
 def default():
-    raise DeprecationWarning("Use @error(404) instead.")
+    raise DeprecationWarning("The default() decorator is deprecated. "\
+                             "Use @error(404) instead.")