From 933d203828164ef4eabcce29667207deb2409569 Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Sun, 18 Sep 2011 15:10:50 +0200
Subject: [PATCH] Started extensions introduction document

---
 docs/contents.rst.inc |  1 +
 docs/extensions.rst   | 48 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 docs/extensions.rst

diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
index 7a8ebb12..a8ebc0d7 100644
--- a/docs/contents.rst.inc
+++ b/docs/contents.rst.inc
@@ -20,6 +20,7 @@ instructions for web development with Flask.
    views
    reqcontext
    blueprints
+   extensions
    shell
    patterns/index
    deploying/index
diff --git a/docs/extensions.rst b/docs/extensions.rst
new file mode 100644
index 00000000..9d00468a
--- /dev/null
+++ b/docs/extensions.rst
@@ -0,0 +1,48 @@
+Flask Extensions
+================
+
+Flask extensions extend the functionality of Flask in various different
+ways.  For instance they add support for databases and other common tasks.
+
+Finding Extensions
+------------------
+
+Flask extensions are listed on the `Flask Extension Registry`_ and can be
+downloaded with ``easy_install`` or ``pip``.  If you add a Flask extension
+as dependency to your ``requirements.rst`` or ``setup.py`` file they are
+usually installed with a simple command or when your application installs.
+
+Using Extensions
+----------------
+
+Extensions typically have documentation that goes along that shows how to
+use it.  There are no general rules in how extensions are supposed to
+behave but they are imported from common locations.  If you have an
+extension called ``Flask-Foo`` or ``Foo-Flask`` it will be always
+importable from ``flask.ext.foo``::
+
+    from flask.ext import foo
+
+Flask < 0.8
+-----------
+
+If you are using Flask 0.7 or earlier the :data:`flask.ext` package will not
+exist, instead you have to import from ``flaskext.foo`` or ``flask_foo``
+depending on how the extension is distributed.
+
+We recommend importing from ``flask.ext`` even with older versions of
+Flask however.  If you have an application that needs to work with
+versions of Flask older than 0.8 you should activate the
+``flaskext_compat`` module which provides the ``flask.ext`` module.  You
+can download it from github: `flaskext_compat.py`_
+
+You can use it like this::
+
+    import flaskext_compat
+    from flask.ext import foo
+
+Once the ``flaskext_compat`` module is imported the :data:`flask.ext` will
+exist and you can start importing from there.
+
+.. _Flask Extension Registry: http://flask.pocoo.org/extensions/
+.. _flaskext_compat.py: https://github.com/mitsuhiko/flask/raw/master/scripts/flaskext_compat.py