Fixed a doc bug and added distribtue docs.

docs/installation.rst

@@ -19,6 +19,8 @@ lighttpd, on Google's App Engine or whatever you have in mind).
 So how do you get all that on your computer in no time?  The most kick-ass
 method is virtualenv, so let's look at that first.
 
+.. _virtualenv:
+
 virtualenv
 ----------
 

docs/patterns/distribute.rst

@@ -0,0 +1,160 @@
+Deploying with Distribute
+=========================
+
+`distribute`_, formerly setuptools, is an extension library that is
+commonly used to (like the name says) distribute Python libraries and
+extensions.  It extends distutils, a basic module installation system
+shipped with Python to also support various more complex constructs that
+make larger applications easier to distribute:
+
+- **support for dependencies**: a library or application can declare a
+  list of other libraries it depends on which will be installed
+  automatically for you.
+- **package registry**: setuptools registers your package with your
+  Python installation.  This makes it possible to query information
+  provided by one package from another package.  The best known feature of
+  this system is the entry point support which allows one package to
+  declare an "entry point" another package can hook into to extend the
+  other package.
+- **installation manager**: `easy_install`, which comes with distribute
+  can install other libraries for you.  You can also use `pip`_ which
+  sooner or later will replace `easy_install` which does more than just
+  installing packages for you.
+
+Flask itself, and all the libraries you can find on the cheeseshop will
+are distributed with either distribute, the older setuptools or distutils.
+
+In this case we assume your application is called
+`yourapplication.py` and you are not using a module, but a `package
+<larger-applications>`_.  Distributing resources with standard modules is
+not supported by `distribute`_ so we will not bother with it.  If you have
+not yet converted your application into a package, head over to the
+:ref:`larger-applications` pattern to see how this can be done.
+
+Basic Setup Script
+------------------
+
+Because you have Flask running, you either have setuptools or distribute
+available on your system anyways.  If you do not, fear not, there is a
+script to install it for you: `distribute_setup.py`_.  Just download and
+run with your Python interpreter.
+
+Standard disclaimer applies: :ref:`you better use a virtualenv
+<virtualenv>`.
+
+Your setup code always goes into a file named `setup.py` next to your
+application.  The name of the file is only convention, but because
+everybody will look for a file with that name, you better not change it.
+
+Yes, even if you are using `distribute`, you are importing from a package
+called `setuptools`.  `distribute` is fully backwards compatible with
+`setuptools`, so it also uses the same import name.
+
+A basic `setup.py` file for a Flask application looks like this::
+
+    from setuptools import setup
+
+    setup(
+        name='Your Application',
+        version='1.0',
+        long_description=__doc__,
+        packages=['yourapplication'],
+        include_package_data=True,
+        zip_safe=False,
+        install_requires=['Flask']
+    )
+
+Please keep in mind that you have to list subpackages explicitly.  If you
+want distribute to lookup the packages for you automatically, you can use
+the `find_packages` function::
+
+    from setuptools import setup, find_packages
+
+    setup(
+        ...
+        packages=find_packages()
+    )
+
+Most parameters to the `setup` function should be self explanatory,
+`include_package_data` and `zip_safe` might not be.
+`include_package_data` tells distribute to look for a `MANIFEST.in` file
+and install all the entries that match as package data.  We will use this
+to distribute the static files and templates along with the Python module
+(see :ref:`distributing-resources`).  The `zip_safe` flag can be used to
+force or prevent zip Archive creation.  In general you probably don't want
+your packages to be installed as zip files because some tools do not
+support them and they make debugging a lot harder.
+
+
+.. _distributing-resources:
+
+Distributing Resources
+----------------------
+
+If you try to install the package you just created, you will notice that
+folders like `static` or `templates` are not installed for you.  The
+reason for this is that distribute does not know which files to add for
+you.  What you should do, is to create a `MANIFEST.in` file next to your
+`setup.py` file.  This file lists all the files that should be added to
+your tarball::
+
+    recursive-include yourapplication/templates
+    recursive-include yourapplication/static
+
+Don't forget that even if you enlist them in your `MANIFEST.in` file, they
+won't be installed for you unless you set the `include_package_data`
+parameter of the `setup` function to `True`!
+
+
+Declaring Dependencies
+----------------------
+
+Dependencies are declared in the `install_requires` parameter as list.
+Each item in that list is the name of a package that should be pulled from
+PyPI on installation.  By default it will always use the most recent
+version, but you can also provide minimum and maximum version
+requirements.  Here some examples::
+
+    install_requires=[
+        'Flask>=0.2',
+        'SQLAlchemy>=0.6',
+        'BrokenPackage>=0.7,<=1.0'
+    ]
+
+I mentioned earlier that dependencies are pulled from PyPI.  What if you
+want to depend on a package that cannot be found on PyPI and won't be
+because it is an internal package you don't want to share with anyone?
+Just still do as if there was a PyPI entry for it and provide a list of
+alternative locations where distribute should look for tarballs::
+
+    dependency_links=['http://example.com/yourfiles']
+
+Make sure that page has a directory listing and the links on the page are
+pointing to the actual tarballs with their correct filenames as this is
+how distribute will find the files.  If you have an internal company
+server that contains the packages, provide the URL to that server there.
+
+
+Installing / Developing
+-----------------------
+
+To install your application (ideally into a virtualenv) just run the
+`setup.py` script with the `install` parameter.  It will install your
+application into the virtualenv's site-packages folder and also download
+and install all dependencies::
+
+    $ python setup.py install
+
+If you are developing on the package and also want the requirements to be
+installed, you can use the `develop` command instead::
+
+    $ python setup.py develop
+
+This has the advantage of just installing a link to the site-packages
+folder instead of copying the data over.  You can then continue to work on
+the code without having to run `install` again after each change.
+
+
+.. _distribute: http://pypi.python.org/pypi/distribute
+.. _pip: http://pypi.python.org/pypi/pip
+.. _distribute_setup.py: http://python-distribute.org/distribute_setup.py

docs/patterns/flashing.rst

@@ -11,6 +11,9 @@ possible to record a message at the end of a request and access it next
 request and only next request.  This is usually combined with a layout
 template that does this.
 
+Simple Flashing
+---------------
+
 So here a full example::
 
     from flask import flash, redirect, url_for, render_template
@@ -79,3 +82,38 @@ And of course the login template:
        <p><input type=submit value=Login>
      </form>
    {% endblock %}
+
+Flashing With Categories
+------------------------
+
+.. versionadded:: 0.5
+
+It is also possible to provide categories when flashing a message.  The
+default category if nothing is provided is ``'message'``.  Alternative
+categories can be used to give the user better feedback.  For example
+error messages could be displayed with a red background.
+
+To flash a message with a different category, just use the second argument
+to the :func:`~flask.flash` function::
+
+    flash(u'Invalid password provided', 'error')
+
+Inside the template you then have to tell the
+:func:`~flask.get_flashed_messages` function to also return the
+categories.  The loop looks slighty different in that situation then:
+
+.. sourcecode:: html+jinja
+
+   {% with messages = get_flashed_messages(with_categories=true) %}
+     {% if messages %}
+       <ul class=flashes>
+       {% for category, message in messages %}
+         <li class="{{ category }}">{{ message }}</li>
+       {% endfor %}
+       </ul>
+     {% endif %}
+   {% endwith %}
+
+This is just one example of how to render these flashed messages.  One
+might also use the category to add a prefix such as
+``<strong>Error:</strong>`` to the message.

docs/patterns/index.rst

@@ -17,6 +17,7 @@ Snippet Archives <http://flask.pocoo.org/snippets/>`_.
    :maxdepth: 2
 
    packages
+   distribute
    sqlite3
    sqlalchemy
    fileuploads