Improved documentation, added a contextmanager for request binding

docs/api.rst

@@ -8,8 +8,158 @@ parts where Flask depends on external libraries, we document the most
 important right here and provide links to the canonical documentation.
 
 
-General Structure
------------------
+Application Object
+------------------
 
 .. autoclass:: Flask
    :members:
+
+Incoming Request Data
+---------------------
+
+.. class:: request
+
+   To access incoming request data, you can use the global `request`
+   object.  Flask parses incoming request data for you and gives you
+   access to it through that global object.  Internally Flask makes
+   sure that you always get the correct data for the active thread if you
+   are in a multithreaded environment.
+
+   The request object is an instance of a :class:`~werkzeug.Request`
+   subclass and provides all of the attributes Werkzeug defines.  This
+   just shows a quick overview of the most important ones.
+
+   .. attribute:: form
+
+      A :class:`~werkzeug.MultiDict` with the parsed form data from `POST`
+      or `PUT` requests.  Please keep in mind that file uploads will not
+      end up here,  but instead in the :attr:`files` attribute.
+
+   .. attribute:: args
+
+      A :class:`~werkzeug.MultiDict` with the parsed contents of the query
+      string.  (The part in the URL after the question mark).
+
+   .. attribute:: values
+
+      A :class:`~werkzeug.CombinedMultiDict` with the contents of both
+      :attr:`form` and :attr:`args`.
+
+   .. attribute:: cookies
+
+      A :class:`dict` with the contents of all cookies transmitted with
+      the request.
+
+   .. attribute:: stream
+
+      If the incoming form data was not encoded with a known encoding (for
+      example it was transmitted as JSON) the data is stored unmodified in
+      this stream for consumption.  For example to read the incoming
+      request data as JSON, one can do the following::
+
+          json_body = simplejson.load(request.stream)
+
+   .. attribute:: files
+
+      A :class:`~werkzeug.MultiDict` with files uploaded as part of a
+      `POST` or `PUT` request.  Each file is stored as
+      :class:`~werkzeug.FileStorage` object.  It basically behaves like a
+      standard file object you know from Python, with the difference that
+      it also has a :meth:`~werkzeug.FileStorage.save` function that can
+      store the file on the filesystem.
+
+   .. attribute:: method
+
+      The current request method (``POST``, ``GET`` etc.)
+
+   .. attribute:: path
+   .. attribute:: script_root
+   .. attribute:: url
+   .. attribute:: base_url
+   .. attribute:: url_root
+
+      Provides different ways to look at the current URL.  Imagine your
+      application is listening on the following URL::
+
+          http://www.example.com/myapplication
+
+      And a user requests the following URL::
+
+          http://www.example.com/myapplication/page.html?x=y
+
+      In this case the values of the above mentioned attributes would be
+      the following:
+
+      ============= ======================================================
+      `path`        ``/page.html``
+      `script_root` ``/myapplication``
+      `url`         ``http://www.example.com/myapplication/page.html``
+      `base_url`    ``http://www.example.com/myapplication/page.html?x=y``
+      `root_url`    ``http://www.example.com/myapplication/``
+      ============= ======================================================
+
+
+Sessions
+--------
+
+If you have the :attr:`Flask.secret_key` set you can use sessions in Flask
+applications.  A session basically makes it possible to remember
+information from one request to another.  The way Flask does this is by
+using a signed cookie.  So the user can look at the session contents, but
+not modify it unless he knows the secret key, so make sure to set that to
+something complex and unguessable.
+
+To access the current session you can use the :class:`session` object:
+
+.. class:: session
+
+   The session object works pretty much like an ordinary dict, with the
+   difference that it keeps track on modifications.
+
+   The following attributes are interesting:
+
+   .. attribute:: new
+
+      `True` if the session is new, `False` otherwise.
+
+   .. attribute:: modified
+
+      `True` if the session object detected a modification.  Be advised
+      that modifications on mutable structures are not picked up
+      automatically, in that situation you have to explicitly set the
+      attribute to `True` yourself.  Here an example::
+
+          # this change is not picked up because a mutable object (here
+          # a list) is changed.
+          session['objects'].append(42)
+          # so mark it as modified yourself
+          session.modified = True
+
+
+Useful Functions and Classes
+----------------------------
+
+.. autofunction:: url_for
+
+.. autofunction:: abort
+
+.. autofunction:: redirect
+
+.. autofunction:: escape
+
+.. autoclass:: Markup
+   :members: escape, unescape, striptags
+
+Message Flashing
+----------------
+
+.. autofunction:: flash
+
+.. autofunction:: get_flashed_messages
+
+Template Rendering
+------------------
+
+.. autofunction:: render_template
+
+.. autofunction:: render_template_string

docs/conf.py

@@ -25,7 +25,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -234,3 +234,8 @@ latex_documents = [
 
 # The depth of the table of contents in toc.ncx.
 #epub_tocdepth = 3
+
+intersphinx_mapping = {
+    'http://docs.python.org/dev': None,
+    'http://werkzeug.pocoo.org/documentation/dev/': None
+}