4 files changed, 50 insertions, 31 deletions
diff --git a/docs/howto/deployment/fastcgi.txt b/docs/howto/deployment/fastcgi.txt
index cf05174390..c2b8aa8b53 100644
--- a/docs/howto/deployment/fastcgi.txt
+++ b/docs/howto/deployment/fastcgi.txt
@@ -1,13 +1,11 @@
-.. _howto-deployment-fastcgi:
-
 ============================================
 How to use Django with FastCGI, SCGI, or AJP
 ============================================
 
 .. highlight:: bash
 
-Although the current preferred setup for running Django is :ref:`Apache with
-mod_wsgi <howto-deployment-modwsgi>`, many people use shared hosting, on
+Although the current preferred setup for running Django is :doc:`Apache with
+mod_wsgi </howto/deployment/modwsgi>`, many people use shared hosting, on
 which protocols such as FastCGI, SCGI or AJP are the only viable options. In
 some setups, these protocols may provide better performance than mod_wsgi_.
 
@@ -22,14 +20,14 @@ serve pages to a Web server. The Web server delegates the incoming Web requests
 (via a socket) to FastCGI, which executes the code and passes the response back
 to the Web server, which, in turn, passes it back to the client's Web browser.
 
-Like mod_python, FastCGI allows code to stay in memory, allowing requests to be
-served with no startup time. Unlike mod_python_ (or `mod_perl`_), a FastCGI
-process doesn't run inside the Web server process, but in a separate,
+Like mod_wsgi, FastCGI allows code to stay in memory, allowing requests to be
+served with no startup time. While mod_wsgi can either be configured embedded
+in the Apache webserver process or as a separate daemon process, a FastCGI
+process never runs inside the Web server process, always in a separate,
 persistent process.
 
 .. _mod_wsgi: http://code.google.com/p/modwsgi/
 .. _mod_perl: http://perl.apache.org/
-.. _mod_python: http://www.modpython.org/
 
 .. admonition:: Why run code in a separate process?
 
@@ -37,8 +35,7 @@ persistent process.
     languages (most notably PHP, Python and Perl) inside the process space of
     your Web server. Although this lowers startup time -- because code doesn't
     have to be read off disk for every request -- it comes at the cost of
-    memory use. For mod_python, for example, every Apache process gets its own
-    Python interpreter, which uses up a considerable amount of RAM.
+    memory use.
 
     Due to the nature of FastCGI, it's even possible to have processes that run
     under a different user account than the Web server process. That's a nice
@@ -74,7 +71,7 @@ TCP socket. What you choose is a manner of preference; a TCP socket is usually
 easier due to permissions issues.
 
 To start your server, first change into the directory of your project (wherever
-your :ref:`manage.py <ref-django-admin>` is), and then run the
+your :doc:`manage.py </ref/django-admin>` is), and then run the
 :djadmin:`runfcgi` command::
 
     ./manage.py runfcgi [options]
@@ -363,7 +360,7 @@ Serving admin media files
 
 Regardless of the server and configuration you eventually decide to use, you
 will also need to give some thought to how to serve the admin media files. The
-advice given in the :ref:`modpython <serving-the-admin-files>` documentation
+advice given in the :ref:`mod_wsgi <serving-the-admin-files>` documentation
 is also applicable in the setups detailed above.
 
 Forcing the URL prefix to a particular value
diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt
index 78cfb037f5..2eff3e6ace 100644
--- a/docs/howto/deployment/index.txt
+++ b/docs/howto/deployment/index.txt
@@ -1,5 +1,3 @@
-.. _howto-deployment-index:
-
 Deploying Django
 ================
 
@@ -10,18 +8,18 @@ ways to easily deploy Django:
 
 .. toctree::
    :maxdepth: 1
-   
+
    modwsgi
-   modpython
    fastcgi
-   
+   mod_python (deprecated) <modpython>
+
 If you're new to deploying Django and/or Python, we'd recommend you try
-:ref:`mod_wsgi <howto-deployment-modwsgi>` first. In most cases it'll be the easiest,
+:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be the easiest,
 fastest, and most stable deployment choice.
 
 .. seealso::
 
     * `Chapter 12 of The Django Book`_ discusses deployment and especially
       scaling in more detail.
-      
+
 .. _chapter 12 of the django book: http://djangobook.com/en/2.0/chapter12/
diff --git a/docs/howto/deployment/modpython.txt b/docs/howto/deployment/modpython.txt
index 143a6d5ae3..a9b665f331 100644
--- a/docs/howto/deployment/modpython.txt
+++ b/docs/howto/deployment/modpython.txt
@@ -4,11 +4,18 @@
 How to use Django with Apache and mod_python
 ============================================
 
+.. warning::
+
+    Support for mod_python will be deprecated in a future release of Django. If
+    you are configuring a new deployment, you are strongly encouraged to
+    consider using :doc:`mod_wsgi </howto/deployment/modwsgi>` or any of the
+    other :doc:`supported backends </howto/deployment/index>`.
+
 .. highlight:: apache
 
 The `mod_python`_ module for Apache_ can be used to deploy Django to a
 production server, although it has been mostly superseded by the simpler
-:ref:`mod_wsgi deployment option <howto-deployment-modwsgi>`.
+:doc:`mod_wsgi deployment option </howto/deployment/modwsgi>`.
 
 mod_python is similar to (and inspired by) `mod_perl`_ : It embeds Python within
 Apache and loads Python code into memory when the server starts. Code stays in
@@ -25,8 +32,8 @@ Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
       Apache, there's no better source than `Apache's own official
       documentation`_
 
-    * You may also be interested in :ref:`How to use Django with FastCGI, SCGI,
-      or AJP <howto-deployment-fastcgi>`.
+    * You may also be interested in :doc:`How to use Django with FastCGI, SCGI,
+      or AJP </howto/deployment/fastcgi>`.
 
 .. _Apache: http://httpd.apache.org/
 .. _mod_python: http://www.modpython.org/
@@ -216,8 +223,6 @@ Or add the debugging information to the template of your page.
 
 .. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html
 
-.. _serving-media-files:
-
 Serving media files
 ===================
 
@@ -269,10 +274,6 @@ the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or
 .. _Apache: http://httpd.apache.org/
 .. _Cherokee: http://www.cherokee-project.com/
 
-.. _howto-deployment-modpython-serving-the-admin-files:
-
-.. _serving-the-admin-files:
-
 Serving the admin files
 =======================
 
@@ -383,7 +384,7 @@ If you get a UnicodeEncodeError
 ===============================
 
 If you're taking advantage of the internationalization features of Django (see
-:ref:`topics-i18n`) and you intend to allow users to upload files, you must
+:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must
 ensure that the environment used to start Apache is configured to accept
 non-ASCII file names. If your environment is not correctly configured, you
 will trigger ``UnicodeEncodeError`` exceptions when calling functions like
diff --git a/docs/howto/deployment/modwsgi.txt b/docs/howto/deployment/modwsgi.txt
index 12de53f53d..e873006af0 100644
--- a/docs/howto/deployment/modwsgi.txt
+++ b/docs/howto/deployment/modwsgi.txt
@@ -1,5 +1,3 @@
-.. _howto-deployment-modwsgi:
-
 ==========================================
 How to use Django with Apache and mod_wsgi
 ==========================================
@@ -55,6 +53,8 @@ just above the final ``import`` line to place your project on the path. Remember
 replace 'mysite.settings' with your correct settings file, and '/usr/local/django'
 with your own project's location.
 
+.. _serving-media-files:
+
 Serving media files
 ===================
 
@@ -108,6 +108,29 @@ in the mod_wsgi documentation on `hosting static files`_.
 
 .. _hosting static files: http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#Hosting_Of_Static_Files
 
+.. _serving-the-admin-files:
+
+Serving the admin files
+=======================
+
+Note that the Django development server automagically serves admin media files,
+but this is not the case when you use any other server arrangement. You're
+responsible for setting up Apache, or whichever media server you're using, to
+serve the admin files.
+
+The admin files live in (:file:`django/contrib/admin/media`) of the Django
+distribution.
+
+Here are two recommended approaches:
+
+    1. Create a symbolic link to the admin media files from within your
+       document root. This way, all of your Django-related files -- code **and**
+       templates -- stay in one place, and you'll still be able to ``svn
+       update`` your code to get the latest admin templates, if they change.
+
+    2. Or, copy the admin media files so that they live within your Apache
+       document root.
+
 Details
 =======