(Re-)added GeoDjango instructions for building pysqlite2 correctly.

This is a partial undo of 1b142ef5dd.

3 files changed, 57 insertions, 4 deletions

diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt
index 3cf8a29822..9c46b19493 100644
--- a/docs/ref/contrib/gis/install/index.txt
+++ b/docs/ref/contrib/gis/install/index.txt
@@ -285,7 +285,7 @@ William Kyngesburye provides a number of `geospatial library binary packages`__
 that make it simple to get GeoDjango installed on OS X without compiling
 them from source.  However, the `Apple Developer Tools`_ are still necessary
 for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS)
-and ``pysqlite2`` (for SpatiaLite).
+and :ref:`pysqlite2` (for SpatiaLite).
 
 .. note::
 
diff --git a/docs/ref/contrib/gis/install/spatialite.txt b/docs/ref/contrib/gis/install/spatialite.txt
index ab40600205..b625942fa6 100644
--- a/docs/ref/contrib/gis/install/spatialite.txt
+++ b/docs/ref/contrib/gis/install/spatialite.txt
@@ -107,6 +107,60 @@ Finally, do the same for the SpatiaLite tools::
 
 __ http://www.gaia-gis.it/gaia-sins/libspatialite-sources/
 
+.. _pysqlite2:
+
+pysqlite2
+^^^^^^^^^
+
+If you've decided to use a :ref:`newer version of pysqlite2
+<using-newer-versions-of-pysqlite>` instead of the ``sqlite3`` Python stdlib
+module, then you need to make sure it can load external extensions (i.e. the
+required ``enable_load_extension`` method is available so ``SpatiaLite`` can be
+loaded).
+
+This might involve building it yourself. For this, download pysqlite2 2.6, and
+untar::
+
+    $ wget https://pypi.python.org/packages/source/p/pysqlite/pysqlite-2.6.3.tar.gz
+    $ tar xzf pysqlite-2.6.3.tar.gz
+    $ cd pysqlite-2.6.3
+
+Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file
+to look like the following:
+
+.. code-block:: ini
+
+    [build_ext]
+    #define=
+    include_dirs=/usr/local/include
+    library_dirs=/usr/local/lib
+    libraries=sqlite3
+    #define=SQLITE_OMIT_LOAD_EXTENSION
+
+or if you are on Mac OS X:
+
+.. code-block:: ini
+
+    [build_ext]
+    #define=
+    include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
+    library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
+    libraries=sqlite3
+    #define=SQLITE_OMIT_LOAD_EXTENSION
+
+.. note::
+
+    The important thing here is to make sure you comment out the
+    ``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs``
+    and ``library_dirs`` settings are uncommented and set to the appropriate
+    path if the SQLite header files and libraries are not in ``/usr/include``
+    and ``/usr/lib``, respectively.
+
+After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script
+to build and install::
+
+    $ sudo python setup.py install
+
 .. _spatialite_macosx:
 
 Mac OS X-specific instructions
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 2b13af8ca2..0ff1861b2a 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -604,9 +604,8 @@ version of SQLite.
 Using newer versions of the SQLite DB-API 2.0 driver
 ----------------------------------------------------
 
-For versions of Python 2.5 or newer that include ``sqlite3`` in the standard
-library Django will now use a ``pysqlite2`` interface in preference to
-``sqlite3`` if it finds one is available.
+Django will use a ``pysqlite2`` module in preference to ``sqlite3`` as shipped
+with the Python standard library if it finds one is available.
 
 This provides the ability to upgrade both the DB-API 2.0 interface or SQLite 3
 itself to versions newer than the ones included with your particular Python