mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-24 06:06:09 +00:00
Code Issues 32 Releases Wiki Activity

Fixed #14141: docs now use the :doc: construct for links between documents.

Browse Source 
Thanks, Ramiro Morales.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13608 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jacob Kaplan-Moss
2010-08-19 19:27:44 +00:00
parent a352154e42
commit 728effcfbd
181 changed files with 1222 additions and 1525 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/topics/auth.txt
View File

@@ -1,5 +1,3 @@
.. _topics-auth:
=============================
User authentication in Django
=============================
@@ -138,8 +136,8 @@ Methods
:class:`~django.contrib.auth.models.User` objects have two many-to-many
fields: models.User. ``groups`` and ``user_permissions``.
:class:`~django.contrib.auth.models.User` objects can access their related
objects in the same way as any other :ref:`Django model
<topics-db-models>`:
objects in the same way as any other :doc:`Django model
</topics/db/models>`:
.. code-block:: python
@@ -537,7 +535,7 @@ First, install the
:class:`~django.contrib.sessions.middleware.SessionMiddleware` and
:class:`~django.contrib.auth.middleware.AuthenticationMiddleware`
middlewares by adding them to your :setting:`MIDDLEWARE_CLASSES` setting. See
the :ref:`session documentation <topics-http-sessions>` for more information.
the :doc:`session documentation </topics/http/sessions>` for more information.
Once you have those middlewares installed, you'll be able to access
:attr:`request.user <django.http.HttpRequest.user>` in views.
@@ -554,7 +552,7 @@ section). You can tell them apart with
else:
# Do something for anonymous users.
.. _howtologauserin:
.. _how-to-log-a-user-in:
How to log a user in
--------------------
@@ -753,7 +751,7 @@ the following line to your URLconf::
template context variables:
* ``form``: A :class:`~django.forms.Form` object representing the login
form. See the :ref:`forms documentation <topics-forms-index>` for
form. See the :doc:`forms documentation </topics/forms/index>` for
more on ``Form`` objects.
* ``next``: The URL to redirect to after successful login. This may
@@ -769,7 +767,7 @@ the following line to your URLconf::
* ``site_name``: An alias for ``site.name``. If you don't have the site
framework installed, this will be set to the value of
:attr:`request.META['SERVER_NAME'] <django.http.HttpRequest.META>`.
For more on sites, see :ref:`ref-contrib-sites`.
For more on sites, see :doc:`/ref/contrib/sites`.
If you'd prefer not to call the template :file:`registration/login.html`,
you can pass the ``template_name`` parameter via the extra arguments to
@@ -1111,7 +1109,7 @@ The permission_required decorator
Limiting access to generic views
--------------------------------
To limit access to a :ref:`generic view <ref-generic-views>`, write a thin
To limit access to a :doc:`generic view </ref/generic-views>`, write a thin
wrapper around the view, and point your URLconf to your wrapper instead of the
generic view itself. For example::
@@ -1228,13 +1226,13 @@ Methods
~~~~~~~
:class:`~django.contrib.auth.models.Permission` objects have the standard
data-access methods like any other :ref:`Django model <ref-models-instances>`.
data-access methods like any other :doc:`Django model </ref/models/instances>`.
Authentication data in templates
================================
The currently logged-in user and his/her permissions are made available in the
:ref:`template context <ref-templates-api>` when you use
:doc:`template context </ref/templates/api>` when you use
:class:`~django.template.context.RequestContext`.
.. admonition:: Technicality
@@ -1323,7 +1321,7 @@ Messages
.. deprecated:: 1.2
This functionality will be removed in Django 1.4. You should use the
:ref:`messages framework <ref-contrib-messages>` for all new projects and
:doc:`messages framework </ref/contrib/messages>` for all new projects and
begin to update your existing code immediately.
The message system is a lightweight way to queue messages for given users.
@@ -1358,7 +1356,7 @@ a playlist::
When you use :class:`~django.template.context.RequestContext`, the currently
logged-in user and his/her messages are made available in the
:ref:`template context <ref-templates-api>` as the template variable
:doc:`template context </ref/templates/api>` as the template variable
``{{ messages }}``. Here's an example of template code that displays messages:
.. code-block:: html+django
@@ -1373,14 +1371,14 @@ logged-in user and his/her messages are made available in the
.. versionchanged:: 1.2
The ``messages`` template variable uses a backwards compatible method in the
:ref:`messages framework <ref-contrib-messages>` to retrieve messages from
:doc:`messages framework </ref/contrib/messages>` to retrieve messages from
both the user ``Message`` model and from the new framework. Unlike in
previous revisions, the messages will not be erased unless they are actually
displayed.
Finally, note that this messages framework only works with users in the user
database. To send messages to anonymous users, use the
:ref:`messages framework <ref-contrib-messages>`.
:doc:`messages framework </ref/contrib/messages>`.
.. _authentication-backends:
@@ -1401,7 +1399,7 @@ plug in other authentication sources. You can override Django's default
database-based scheme, or you can use the default system in tandem with other
systems.
See the :ref:`authentication backend reference <ref-authentication-backends>`
See the :doc:`authentication backend reference </ref/authbackends>`
for information on the authentication backends included with Django.
Specifying authentication backends
@@ -1410,9 +1408,9 @@ Specifying authentication backends
Behind the scenes, Django maintains a list of "authentication backends" that it
checks for authentication. When somebody calls
:func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log
a user in` above -- Django tries authenticating across all of its
authentication backends. If the first authentication method fails, Django tries
the second one, and so on, until all backends have been attempted.
a user in <how-to-log-a-user-in>` above -- Django tries authenticating across
all of its authentication backends. If the first authentication method fails,
Django tries the second one, and so on, until all backends have been attempted.
The list of authentication backends to use is specified in the
:setting:`AUTHENTICATION_BACKENDS` setting. This should be a tuple of Python
@@ -1592,7 +1590,7 @@ object permissions will always return ``False`` or an empty list (depending on
the check performed).
To enable object permissions in your own
:ref:`authentication backend <ref-authentication-backends>` you'll just have
:doc:`authentication backend </ref/authbackends>` you'll just have
to allow passing an ``obj`` parameter to the permission methods and set the
``supports_object_permissions`` class attribute to ``True``.

6
docs/topics/cache.txt
View File

@@ -1,5 +1,3 @@
.. _topics-cache:
========================
Django's cache framework
========================
@@ -344,7 +342,7 @@ Additionally, the cache middleware automatically sets a few headers in each
* Sets the ``Cache-Control`` header to give a max age for the page --
again, from the ``CACHE_MIDDLEWARE_SECONDS`` setting.
See :ref:`topics-http-middleware` for more on middleware.
See :doc:`/topics/http/middleware` for more on middleware.
.. versionadded:: 1.0
@@ -365,7 +363,7 @@ include the name of the active :term:`language<language code>`.
This allows you to easily cache multilingual sites without having to create
the cache key yourself.
See :ref:`topics-i18n-deployment` for more on how Django discovers the active
See :doc:`/topics/i18n/deployment` for more on how Django discovers the active
language.
__ `Controlling cache: Using other headers`_

2
docs/topics/conditional-view-processing.txt
View File

@@ -1,5 +1,3 @@
.. _topics-conditional-processing:
===========================
Conditional View Processing
===========================

6
docs/topics/db/aggregation.txt
View File

@@ -1,5 +1,3 @@
.. _topics-db-aggregation:
===========
Aggregation
===========
@@ -8,7 +6,7 @@ Aggregation
.. currentmodule:: django.db.models
The topic guide on :ref:`Django's database-abstraction API <topics-db-queries>`
The topic guide on :doc:`Django's database-abstraction API </topics/db/queries>`
described the way that you can use Django queries that create,
retrieve, update and delete individual objects. However, sometimes you will
need to retrieve values that are derived by summarizing or *aggregating* a
@@ -363,7 +361,7 @@ you also select in a ``values()`` call.
for you. The main reason is consistency with ``distinct()`` and other
places: Django **never** removes ordering constraints that you have
specified (and we can't change those other methods' behavior, as that
would violate our :ref:`misc-api-stability` policy).
would violate our :doc:`/misc/api-stability` policy).
Aggregating annotations
-----------------------

2
docs/topics/db/index.txt
View File

@@ -1,5 +1,3 @@
.. _topics-db-index:
Models and databases
====================

6
docs/topics/db/managers.txt
View File

@@ -1,5 +1,3 @@
.. _topics-db-managers:
========
Managers
========
@@ -12,7 +10,7 @@ A ``Manager`` is the interface through which database query operations are
provided to Django models. At least one ``Manager`` exists for every model in
a Django application.
The way ``Manager`` classes work is documented in :ref:`topics-db-queries`;
The way ``Manager`` classes work is documented in :doc:`/topics/db/queries`;
this document specifically touches on model options that customize ``Manager``
behavior.
@@ -325,7 +323,7 @@ it will use :class:`django.db.models.Manager`.
attribute only controlled the type of manager used for related field
access, which is where the name came from. As it became clear the concept
was more broadly useful, the name hasn't been changed. This is primarily
so that existing code will :ref:`continue to work <misc-api-stability>` in
so that existing code will :doc:`continue to work </misc/api-stability>` in
future Django versions.
Writing Correct Managers For Use In Automatic Manager Instances

18
docs/topics/db/models.txt
View File

@@ -1,5 +1,3 @@
.. _topics-db-models:
======
Models
======
@@ -18,7 +16,7 @@ The basics:
* Each attribute of the model represents a database field.
* With all of this, Django gives you an automatically-generated
database-access API; see :ref:`topics-db-queries`.
database-access API; see :doc:`/topics/db/queries`.
.. seealso::
@@ -64,7 +62,7 @@ Some technical notes:
* The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
syntax, but it's worth noting Django uses SQL tailored to the database
backend specified in your :ref:`settings file <topics-settings>`.
backend specified in your :doc:`settings file </topics/settings>`.
Using models
============
@@ -126,7 +124,7 @@ determine a few things:
Django ships with dozens of built-in field types; you can find the complete list
in the :ref:`model field reference <model-field-types>`. You can easily write
your own fields if Django's built-in ones don't do the trick; see
:ref:`howto-custom-model-fields`.
:doc:`/howto/custom-model-fields`.
Field options
-------------
@@ -612,7 +610,7 @@ Custom field types
If one of the existing model fields cannot be used to fit your purposes, or if
you wish to take advantage of some less common database column types, you can
create your own field class. Full coverage of creating your own fields is
provided in :ref:`howto-custom-model-fields`.
provided in :doc:`/howto/custom-model-fields`.
.. _meta-options:
@@ -634,8 +632,8 @@ human-readable singular and plural names (:attr:`~Options.verbose_name` and
:attr:`~Options.verbose_name_plural`). None are required, and adding ``class
Meta`` to a model is completely optional.
A complete list of all possible ``Meta`` options can be found in the :ref:`model
option reference <ref-models-options>`.
A complete list of all possible ``Meta`` options can be found in the :doc:`model
option reference </ref/models/options>`.
.. _model-methods:
@@ -684,7 +682,7 @@ properties`_.
.. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property
The :ref:`model instance reference <ref-models-instances>` has a complete list
The :doc:`model instance reference </ref/models/instances>` has a complete list
of :ref:`methods automatically given to each model <model-instance-methods>`.
You can override most of these -- see `overriding predefined model methods`_,
below -- but there are a couple that you'll almost always want to define:
@@ -763,7 +761,7 @@ Executing custom SQL
Another common pattern is writing custom SQL statements in model methods and
module-level methods. For more details on using raw SQL, see the documentation
on :ref:`using raw SQL<topics-db-sql>`.
on :doc:`using raw SQL</topics/db/sql>`.
.. _model-inheritance:

2
docs/topics/db/multi-db.txt
View File

@@ -1,5 +1,3 @@
.. _topics-db-multi-db:
==================
Multiple databases
==================

18
docs/topics/db/optimization.txt
View File

@@ -1,5 +1,3 @@
.. _topics-db-optimization:
============================
Database access optimization
============================
@@ -45,13 +43,13 @@ Use standard DB optimization techniques
We will assume you have done the obvious things above. The rest of this document
focuses on how to use Django in such a way that you are not doing unnecessary
work. This document also does not address other optimization techniques that
apply to all expensive operations, such as :ref:`general purpose caching
<topics-cache>`.
apply to all expensive operations, such as :doc:`general purpose caching
</topics/cache>`.
Understand QuerySets
====================
Understanding :ref:`QuerySets <ref-models-querysets>` is vital to getting good
Understanding :doc:`QuerySets </ref/models/querysets>` is vital to getting good
performance with simple code. In particular:
Understand QuerySet evaluation
@@ -114,7 +112,7 @@ For instance:
* Use :ref:`F() object query expressions <query-expressions>` to do filtering
against other fields within the same model.
* Use :ref:`annotate to do aggregation in the database <topics-db-aggregation>`.
* Use :doc:`annotate to do aggregation in the database </topics/db/aggregation>`.
If these aren't enough to generate the SQL you need:
@@ -128,8 +126,8 @@ explicitly added to the query. If that still isn't powerful enough:
Use raw SQL
-----------
Write your own :ref:`custom SQL to retrieve data or populate models
<topics-db-sql>`. Use ``django.db.connection.queries`` to find out what Django
Write your own :doc:`custom SQL to retrieve data or populate models
</topics/db/sql>`. Use ``django.db.connection.queries`` to find out what Django
is writing for you and start from there.
Retrieve everything at once if you know you will need it
@@ -148,7 +146,7 @@ Understand :ref:`QuerySet.select_related() <select-related>` thoroughly, and use
* in view code,
* and in :ref:`managers and default managers <topics-db-managers>` where
* and in :doc:`managers and default managers </topics/db/managers>` where
appropriate. Be aware when your manager is and is not used; sometimes this is
tricky so don't make assumptions.
@@ -243,7 +241,7 @@ individual, use a bulk SQL UPDATE statement, via :ref:`QuerySet.update()
Note, however, that these bulk update methods cannot call the ``save()`` or ``delete()``
methods of individual instances, which means that any custom behaviour you have
added for these methods will not be executed, including anything driven from the
normal database object :ref:`signals <ref-signals>`.
normal database object :doc:`signals </ref/signals>`.
Use foreign key values directly
-------------------------------

10
docs/topics/db/queries.txt
View File

@@ -1,15 +1,13 @@
.. _topics-db-queries:
==============
Making queries
==============
.. currentmodule:: django.db.models
Once you've created your :ref:`data models <topics-db-models>`, Django
Once you've created your :doc:`data models </topics/db/models>`, Django
automatically gives you a database-abstraction API that lets you create,
retrieve, update and delete objects. This document explains how to use this
API. Refer to the :ref:`data model reference <ref-models-index>` for full
API. Refer to the :doc:`data model reference </ref/models/index>` for full
details of all the various model lookup options.
Throughout this guide (and in the reference), we'll refer to the following
@@ -937,7 +935,7 @@ be accessed from an instance::
In addition to the ``QuerySet`` methods defined in "Retrieving objects" above,
the ``ForeignKey`` ``Manager`` has additional methods used to handle the set of
related objects. A synopsis of each is below, and complete details can be found
in the :ref:`related objects reference <ref-models-relations>`.
in the :doc:`related objects reference </ref/models/relations>`.
``add(obj1, obj2, ...)``
Adds the specified model objects to the related object set.
@@ -1067,7 +1065,7 @@ Falling back to raw SQL
If you find yourself needing to write an SQL query that is too complex for
Django's database-mapper to handle, you can fall back on writing SQL by hand.
Django has a couple of options for writing raw SQL queries; see
:ref:`topics-db-sql`.
:doc:`/topics/db/sql`.
Finally, it's important to note that the Django database layer is merely an
interface to your database. You can access your database via other tools,

6
docs/topics/db/sql.txt
View File

@@ -1,12 +1,10 @@
.. _topics-db-sql:
==========================
Performing raw SQL queries
==========================
.. currentmodule:: django.db.models
When the :ref:`model query APIs <topics-db-queries>` don't go far enough, you
When the :doc:`model query APIs </topics/db/queries>` don't go far enough, you
can fall back to writing raw SQL. Django gives you two ways of performing raw
SQL queries: you can use :meth:`Manager.raw()` to `perform raw queries and
return model instances`__, or you can avoid the model layer entirely and
@@ -269,7 +267,7 @@ Connections and cursors
-----------------------
``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_
(except when it comes to :ref:`transaction handling <topics-db-transactions>`).
(except when it comes to :doc:`transaction handling </topics/db/transactions>`).
If you're not familiar with the Python DB-API, note that the SQL statement in
``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters
directly within the SQL. If you use this technique, the underlying database

4
docs/topics/db/transactions.txt
View File

@@ -1,5 +1,3 @@
.. _topics-db-transactions:
==============================
Managing database transactions
==============================
@@ -306,7 +304,7 @@ Database-level autocommit
.. versionadded:: 1.1
With PostgreSQL 8.2 or later, there is an advanced option to run PostgreSQL
with :ref:`database-level autocommit <ref-databases>`. If you use this option,
with :doc:`database-level autocommit </ref/databases>`. If you use this option,
there is no constantly open transaction, so it is always possible to continue
after catching an exception. For example::

2
docs/topics/email.txt
View File

@@ -1,5 +1,3 @@
.. _topics-email:
==============
Sending e-mail
==============

10
docs/topics/files.txt
View File

@@ -1,5 +1,3 @@
.. _topics-files:
==============
Managing files
==============
@@ -70,7 +68,7 @@ using a Python built-in ``file`` object::
>>> myfile = File(f)
Now you can use any of the ``File`` attributes and methods documented in
:ref:`ref-files-file`.
:doc:`/ref/files/file`.
File storage
============
@@ -84,7 +82,7 @@ setting; if you don't explicitly provide a storage system, this is the one that
will be used.
See below for details of the built-in default file storage system, and see
:ref:`howto-custom-file-storage` for information on writing your own file
:doc:`/howto/custom-file-storage` for information on writing your own file
storage system.
Storage objects
@@ -111,7 +109,7 @@ useful -- you can use the global default storage system::
>>> default_storage.exists(path)
False
See :ref:`ref-files-storage` for the file storage API.
See :doc:`/ref/files/storage` for the file storage API.
The built-in filesystem storage class
-------------------------------------
@@ -143,5 +141,5 @@ For example, the following code will store uploaded files under
...
photo = models.ImageField(storage=fs)
:ref:`Custom storage systems <howto-custom-file-storage>` work the same way: you
:doc:`Custom storage systems </howto/custom-file-storage>` work the same way: you
can pass them in as the ``storage`` argument to a ``FileField``.

1
docs/topics/forms/formsets.txt
View File

@@ -1,4 +1,3 @@
.. _topics-forms-formsets:
.. _formsets:
Formsets

14
docs/topics/forms/index.txt
View File

@@ -1,5 +1,3 @@
.. _topics-forms-index:
==================
Working with forms
==================
@@ -7,8 +5,8 @@ Working with forms
.. admonition:: About this document
This document provides an introduction to Django's form handling features.
For a more detailed look at the forms API, see :ref:`ref-forms-api`. For
documentation of the available field types, see :ref:`ref-forms-fields`.
For a more detailed look at the forms API, see :doc:`/ref/forms/api`. For
documentation of the available field types, see :doc:`/ref/forms/fields`.
.. highlightlang:: html+django
@@ -77,10 +75,10 @@ personal Web site:
A form is composed of ``Field`` objects. In this case, our form has four
fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. ``CharField``,
``EmailField`` and ``BooleanField`` are just three of the available field types;
a full list can be found in :ref:`ref-forms-fields`.
a full list can be found in :doc:`/ref/forms/fields`.
If your form is going to be used to directly add or edit a Django model, you can
use a :ref:`ModelForm <topics-forms-modelforms>` to avoid duplicating your model
use a :doc:`ModelForm </topics/forms/modelforms>` to avoid duplicating your model
description.
Using a form in a view
@@ -163,7 +161,7 @@ Extending the above example, here's how the form data could be processed:
send_mail(subject, message, sender, recipients)
return HttpResponseRedirect('/thanks/') # Redirect after POST
For more on sending e-mail from Django, see :ref:`topics-email`.
For more on sending e-mail from Django, see :doc:`/topics/email`.
Displaying a form using a template
----------------------------------
@@ -397,4 +395,4 @@ This covers the basics, but forms can do a whole lot more:
.. seealso::
The :ref:`form API reference <ref-forms-index>`.
The :doc:`form API reference </ref/forms/index>`.

2
docs/topics/forms/media.txt
View File

@@ -1,5 +1,3 @@
.. _topics-forms-media:
Form Media
==========

8
docs/topics/forms/modelforms.txt
View File

@@ -1,5 +1,3 @@
.. _topics-forms-modelforms:
==========================
Creating forms from models
==========================
@@ -446,7 +444,7 @@ parameter when declaring the form field::
class Meta:
model = Article
See the :ref:`form field documentation <ref-forms-fields>` for more information
See the :doc:`form field documentation </ref/forms/fields>` for more information
on fields and their arguments.
Changing the order of fields
@@ -540,7 +538,7 @@ Interaction with model validation
As part of its validation process, ``ModelForm`` will call the ``clean()``
method of each field on your model that has a corresponding field on your form.
If you have excluded any model fields, validation will not be run on those
fields. See the :ref:`form validation <ref-forms-validation>` documentation
fields. See the :doc:`form validation </ref/forms/validation>` documentation
for more on how field cleaning and validation work. Also, your model's
``clean()`` method will be called before any uniqueness checks are made. See
:ref:`Validating objects <validating-objects>` for more information on the
@@ -551,7 +549,7 @@ model's ``clean()`` hook.
Model formsets
==============
Like :ref:`regular formsets <topics-forms-formsets>`, Django provides a couple
Like :doc:`regular formsets </topics/forms/formsets>`, Django provides a couple
of enhanced formset classes that make it easy to work with Django models. Let's
reuse the ``Author`` model from above::

10
docs/topics/generic-views.txt
View File

@@ -1,5 +1,3 @@
.. _topics-generic-views:
=============
Generic views
=============
@@ -192,7 +190,7 @@ might look like the following::
That's really all there is to it. All the cool features of generic views come
from changing the "info" dictionary passed to the generic view. The
:ref:`generic views reference<ref-generic-views>` documents all the generic
:doc:`generic views reference</ref/generic-views>` documents all the generic
views and all their options in detail; the rest of this document will consider
some of the common ways you might customize and extend generic views.
@@ -315,9 +313,9 @@ Viewing subsets of objects
Now let's take a closer look at this ``queryset`` key we've been using all
along. Most generic views take one of these ``queryset`` arguments -- it's how
the view knows which set of objects to display (see :ref:`topics-db-queries` for
the view knows which set of objects to display (see :doc:`/topics/db/queries` for
more information about ``QuerySet`` objects, and see the
:ref:`generic views reference<ref-generic-views>` for the complete details).
:doc:`generic views reference</ref/generic-views>` for the complete details).
To pick a simple example, we might want to order a list of books by
publication date, with the most recent first:
@@ -365,7 +363,7 @@ We'll deal with this problem in the next section.
If you get a 404 when requesting ``/books/acme/``, check to ensure you
actually have a Publisher with the name 'ACME Publishing'. Generic
views have an ``allow_empty`` parameter for this case. See the
:ref:`generic views reference<ref-generic-views>` for more details.
:doc:`generic views reference</ref/generic-views>` for more details.
Complex filtering with wrapper functions
----------------------------------------

6
docs/topics/http/file-uploads.txt
View File

@@ -1,5 +1,3 @@
.. _topics-http-file-uploads:
============
File Uploads
============
@@ -10,8 +8,8 @@ File Uploads
When Django handles a file upload, the file data ends up placed in
:attr:`request.FILES <django.http.HttpRequest.FILES>` (for more on the
``request`` object see the documentation for :ref:`request and response objects
<ref-request-response>`). This document explains how files are stored on disk
``request`` object see the documentation for :doc:`request and response objects
</ref/request-response>`). This document explains how files are stored on disk
and in memory, and how to customize the default behavior.
Basic file uploads

4
docs/topics/http/generic-views.txt
View File

@@ -1,7 +1,5 @@
.. _topics-http-generic-views:
=============
Generic views
=============
See :ref:`ref-generic-views`.
See :doc:`/ref/generic-views`.

2
docs/topics/http/index.txt
View File

@@ -1,5 +1,3 @@
.. _topics-http-index:
Handling HTTP requests
======================

14
docs/topics/http/middleware.txt
View File

@@ -1,5 +1,3 @@
.. _topics-http-middleware:
==========
Middleware
==========
@@ -14,8 +12,8 @@ an ``"X-View"`` HTTP header to every response to a ``HEAD`` request.
This document explains how middleware works, how you activate middleware, and
how to write your own middleware. Django ships with some built-in middleware
you can use right out of the box; they're documented in the :ref:`built-in
middleware reference <ref-middleware>`.
you can use right out of the box; they're documented in the :doc:`built-in
middleware reference </ref/middleware>`.
Activating middleware
=====================
@@ -173,9 +171,9 @@ Guidelines
cares about is that the :setting:`MIDDLEWARE_CLASSES` setting includes
the path to it.
* Feel free to look at :ref:`Django's available middleware
<ref-middleware>` for examples.
* Feel free to look at :doc:`Django's available middleware
</ref/middleware>` for examples.
* If you write a middleware component that you think would be useful to
other people, contribute to the community! :ref:`Let us know
<internals-contributing>`, and we'll consider adding it to Django.
other people, contribute to the community! :doc:`Let us know
</internals/contributing>`, and we'll consider adding it to Django.

10
docs/topics/http/sessions.txt
View File

@@ -1,5 +1,3 @@
.. _topics-http-sessions:
===================
How to use sessions
===================
@@ -15,7 +13,7 @@ Cookies contain a session ID -- not the data itself.
Enabling sessions
=================
Sessions are implemented via a piece of :ref:`middleware <ref-middleware>`.
Sessions are implemented via a piece of :doc:`middleware </ref/middleware>`.
To enable session functionality, do the following:
@@ -56,8 +54,8 @@ For better performance, you may want to use a cache-based session backend.
Django 1.0 did not include the ``cached_db`` session backend.
To store session data using Django's cache system, you'll first need to make
sure you've configured your cache; see the :ref:`cache documentation
<topics-cache>` for details.
sure you've configured your cache; see the :doc:`cache documentation
</topics/cache>` for details.
.. warning::
@@ -412,7 +410,7 @@ in the past -- but your application may have different requirements.
Settings
========
A few :ref:`Django settings <ref-settings>` give you control over session behavior:
A few :doc:`Django settings </ref/settings>` give you control over session behavior:
SESSION_ENGINE
--------------

2
docs/topics/http/shortcuts.txt
View File

@@ -1,5 +1,3 @@
.. _topics-http-shortcuts:
=========================
Django shortcut functions
=========================

8
docs/topics/http/urls.txt
View File

@@ -1,5 +1,3 @@
.. _topics-http-urls:
==============
URL dispatcher
==============
@@ -335,7 +333,7 @@ The view prefix
You can specify a common prefix in your ``patterns()`` call, to cut down on
code duplication.
Here's the example URLconf from the :ref:`Django overview <intro-overview>`::
Here's the example URLconf from the :doc:`Django overview </intro/overview>`::
from django.conf.urls.defaults import *
@@ -537,8 +535,8 @@ In this example, for a request to ``/blog/2005/``, Django will call the
year='2005', foo='bar'
This technique is used in :ref:`generic views <ref-generic-views>` and in the
:ref:`syndication framework <ref-contrib-syndication>` to pass metadata and
This technique is used in :doc:`generic views </ref/generic-views>` and in the
:doc:`syndication framework </ref/contrib/syndication>` to pass metadata and
options to views.
.. admonition:: Dealing with conflicts

4
docs/topics/http/views.txt
View File

@@ -1,5 +1,3 @@
.. _topics-http-views:
=============
Writing Views
=============
@@ -59,7 +57,7 @@ Mapping URLs to Views
So, to recap, this view function returns an HTML page that includes the current
date and time. To display this view at a particular URL, you'll need to create a
*URLconf*; see :ref:`topics-http-urls` for instructions.
*URLconf*; see :doc:`/topics/http/urls` for instructions.
Returning errors
================

6
docs/topics/i18n/deployment.txt
View File

@@ -1,5 +1,3 @@
.. _topics-i18n-deployment:
==========================
Deployment of translations
==========================
@@ -72,8 +70,8 @@ For example, your ``MIDDLEWARE_CLASSES`` might look like this::
'django.middleware.common.CommonMiddleware',
)
(For more on middleware, see the :ref:`middleware documentation
<topics-http-middleware>`.)
(For more on middleware, see the :doc:`middleware documentation
</topics/http/middleware>`.)
``LocaleMiddleware`` tries to determine the user's language preference by
following this algorithm:

8
docs/topics/i18n/index.txt
View File

@@ -1,5 +1,3 @@
.. _topics-i18n:
=====================================
Internationalization and localization
=====================================
@@ -23,10 +21,10 @@ associated with each of these tasks (although it's perfectly normal if you
find yourself performing more than one of these roles):
* For application authors wishing to make sure their Django apps can be
used in different locales: :ref:`topics-i18n-internationalization`.
* For translators wanting to translate Django apps: :ref:`topics-i18n-localization`.
used in different locales: :doc:`/topics/i18n/internationalization`.
* For translators wanting to translate Django apps: :doc:`/topics/i18n/localization`.
* For system administrators/final users setting up internationalized apps or
developers integrating third party apps: :ref:`topics-i18n-deployment`.
developers integrating third party apps: :doc:`/topics/i18n/deployment`.
.. toctree::
:hidden:

6
docs/topics/i18n/internationalization.txt
View File

@@ -1,5 +1,3 @@
.. _topics-i18n-internationalization:
====================
Internationalization
====================
@@ -242,7 +240,7 @@ If you don't like the verbose name ``ugettext_lazy``, you can just alias it as
class MyThing(models.Model):
name = models.CharField(help_text=_('This is the help text'))
Always use lazy translations in :ref:`Django models <topics-db-models>`.
Always use lazy translations in :doc:`Django models </topics/db/models>`.
Field names and table names should be marked for translation (otherwise, they
won't be translated in the admin interface). This means writing explicit
``verbose_name`` and ``verbose_name_plural`` options in the ``Meta`` class,
@@ -332,7 +330,7 @@ Specifying translation strings: In template code
.. highlightlang:: html+django
Translations in :ref:`Django templates <topics-templates>` uses two template
Translations in :doc:`Django templates </topics/templates>` uses two template
tags and a slightly different syntax than in Python code. To give your template
access to these tags, put ``{% load i18n %}`` toward the top of your template.

4
docs/topics/i18n/localization.txt
View File

@@ -1,5 +1,3 @@
.. _topics-i18n-localization:
============
Localization
============
@@ -12,7 +10,7 @@ files`_ and `locale aware date, time and numbers input/output in forms`_
.. seealso::
The :ref:`howto-i18n` document included with the Django HOW-TO documents collection.
The :doc:`/howto/i18n` document included with the Django HOW-TO documents collection.
.. _how-to-create-language-files:

2
docs/topics/index.txt
View File

@@ -1,5 +1,3 @@
.. _topics-index:
Using Django
============

22
docs/topics/install.txt
View File

@@ -1,5 +1,3 @@
.. _topics-install:
=====================
How to install Django
=====================
@@ -13,7 +11,7 @@ Being a Python Web framework, Django requires Python.
It works with any Python version from 2.4 to 2.7 (due to backwards
incompatibilities in Python 3.0, Django does not currently work with
Python 3.0; see :ref:`the Django FAQ <faq-install>` for more
Python 3.0; see :doc:`the Django FAQ </faq/install>` for more
information on supported Python versions and the 3.0 transition).
Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
@@ -22,7 +20,7 @@ probably already have it installed.
.. admonition:: Django on Jython
If you use Jython_ (a Python implementation for the Java platform), you'll
need to follow a few additional steps. See :ref:`howto-jython` for details.
need to follow a few additional steps. See :doc:`/howto/jython` for details.
.. _jython: http://jython.org/
@@ -41,12 +39,12 @@ other server arrangements. Make sure you have Apache installed, with the
mod_wsgi module activated. Django will work with any version of Apache that
supports mod_wsgi.
See :ref:`How to use Django with mod_wsgi <howto-deployment-modwsgi>` for
See :doc:`How to use Django with mod_wsgi </howto/deployment/modwsgi>` for
information on how to configure mod_wsgi once you have it installed.
If you can't use mod_wsgi for some reason, fear not: Django supports many other
deployment options. A great second choice is :ref:`mod_python
<howto-deployment-modpython>`, the predecessor to mod_wsgi. Additionally, Django
deployment options. A great second choice is :doc:`mod_python
</howto/deployment/modpython>`, the predecessor to mod_wsgi. Additionally, Django
follows the WSGI_ spec, which allows it to run on a variety of server platforms.
See the `server-arrangements wiki page`_ for specific installation instructions
for each platform.
@@ -90,8 +88,8 @@ database bindings are installed.
If you're on Windows, check out the unofficial `compiled Windows version`_.
* If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher. You
will also want to read the database-specific notes for the :ref:`MySQL
backend <ref-databases>`.
will also want to read the database-specific notes for the :doc:`MySQL
backend </ref/databases>`.
* If you're using SQLite and Python 2.4, you'll need pysqlite_. Use version
2.0.3 or higher. Python 2.5 ships with an SQLite wrapper in the standard
@@ -115,7 +113,7 @@ can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and
``ALTER TABLE`` privileges during ``syncdb`` but won't issue
``ALTER TABLE`` statements on a table once ``syncdb`` has created it.
If you're using Django's :ref:`testing framework<topics-testing>` to test database queries,
If you're using Django's :doc:`testing framework</topics/testing>` to test database queries,
Django will need permission to create a test database.
.. _PostgreSQL: http://www.postgresql.org/
@@ -177,7 +175,7 @@ It's easy, no matter which way you choose.
Installing a distribution-specific package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Check the :ref:`distribution specific notes <misc-distributions>` to see if your
Check the :doc:`distribution specific notes </misc/distributions>` to see if your
platform/distribution provides official Django packages/installers.
Distribution-provided packages will typically allow for automatic installation
of dependencies and easy upgrade paths.
@@ -265,7 +263,7 @@ latest bug fixes and improvements, follow these instructions:
Apache configuration file.
More information about deployment is available, of course, in our
:ref:`How to use Django with mod_python <howto-deployment-modpython>`
:doc:`How to use Django with mod_python </howto/deployment/modpython>`
documentation.
4. On Unix-like systems, create a symbolic link to the file

2
docs/topics/pagination.txt
View File

@@ -1,5 +1,3 @@
.. _topics-pagination:
==========
Pagination
==========

2
docs/topics/serialization.txt
View File

@@ -1,5 +1,3 @@
.. _topics-serialization:
==========================
Serializing Django objects
==========================

8
docs/topics/settings.txt
View File

@@ -1,5 +1,3 @@
.. _topics-settings:
===============
Django settings
===============
@@ -46,7 +44,7 @@ Python `import search path`_.
The django-admin.py utility
---------------------------
When using :ref:`django-admin.py <ref-django-admin>`, you can either set the
When using :doc:`django-admin.py </ref/django-admin>`, you can either set the
environment variable once, or explicitly pass in the settings module each time
you run the utility.
@@ -78,7 +76,7 @@ settings file to use. Do that with ``SetEnv``::
SetEnv DJANGO_SETTINGS_MODULE mysite.settings
</Location>
Read the :ref:`Django mod_python documentation <howto-deployment-modpython>` for
Read the :doc:`Django mod_python documentation </howto/deployment/modpython>` for
more information.
Default settings
@@ -151,7 +149,7 @@ read it. This is especially important in a shared-hosting environment.
Available settings
==================
For a full list of available settings, see the :ref:`settings reference <ref-settings>`.
For a full list of available settings, see the :doc:`settings reference </ref/settings>`.
Creating your own settings
==========================

8
docs/topics/signals.txt
View File

@@ -1,5 +1,3 @@
.. _topics-signals:
=======
Signals
=======
@@ -13,7 +11,7 @@ signals allow certain *senders* to notify a set of *receivers* that some action
has taken place. They're especially useful when many pieces of code may be
interested in the same events.
Django provides a :ref:`set of built-in signals <ref-signals>` that let user
Django provides a :doc:`set of built-in signals </ref/signals>` that let user
code get notified by Django itself of certain actions. These include some useful
notifications:
@@ -38,7 +36,7 @@ notifications:
Sent when Django starts or finishes an HTTP request.
See the :ref:`built-in signal documentation <ref-signals>` for a complete list,
See the :doc:`built-in signal documentation </ref/signals>` for a complete list,
and a complete explanation of each signal.
You can also `define and send your own custom signals`_; see below.
@@ -128,7 +126,7 @@ The ``my_handler`` function will only be called when an instance of ``MyModel``
is saved.
Different signals use different objects as their senders; you'll need to consult
the :ref:`built-in signal documentation <ref-signals>` for details of each
the :doc:`built-in signal documentation </ref/signals>` for details of each
particular signal.
Defining and sending signals

20
docs/topics/templates.txt
View File

@@ -1,5 +1,3 @@
.. _topics-templates:
============================
The Django template language
============================
@@ -8,7 +6,7 @@ The Django template language
This document explains the language syntax of the Django template system. If
you're looking for a more technical perspective on how it works and how to
extend it, see :ref:`ref-templates-api`.
extend it, see :doc:`/ref/templates/api`.
Django's template language is designed to strike a balance between power and
ease. It's designed to feel comfortable to those used to working with HTML. If
@@ -28,8 +26,8 @@ or CheetahTemplate_, you should feel right at home with Django's templates.
tag for looping, etc. -- but these are not simply executed as the
corresponding Python code, and the template system will not execute
arbitrary Python expressions. Only the tags, filters and syntax listed below
are supported by default (although you can add :ref:`your own extensions
<howto-custom-template-tags>` to the template language as needed).
are supported by default (although you can add :doc:`your own extensions
</howto/custom-template-tags>` to the template language as needed).
.. _`The Django template language: For Python programmers`: ../templates_python/
.. _Smarty: http://smarty.php.net/
@@ -140,7 +138,7 @@ template filters:
If ``value`` isn't provided or is empty, the above will display
"``nothing``".
:tfilter:`length`
Returns the length of the value. This works for both strings and lists;
for example::
@@ -148,7 +146,7 @@ template filters:
{{ value|length }}
If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``.
:tfilter:`striptags`
Strips all [X]HTML tags. For example::
@@ -161,7 +159,7 @@ Again, these are just a few examples; see the :ref:`built-in filter reference
<ref-templates-builtins-filters>` for the complete list.
You can also create your own custom template filters; see
:ref:`howto-custom-template-tags`.
:doc:`/howto/custom-template-tags`.
Tags
====
@@ -217,7 +215,7 @@ Again, the above is only a selection of the whole list; see the :ref:`built-in
tag reference <ref-templates-builtins-tags>` for the complete list.
You can also create your own custom template tags; see
:ref:`howto-custom-template-tags`.
:doc:`/howto/custom-template-tags`.
Comments
========
@@ -634,8 +632,8 @@ The ``{% load %}`` tag can take multiple library names, separated by spaces.
Example::
{% load comments i18n %}
See :ref:`howto-custom-template-tags` for information on writing your own custom
See :doc:`/howto/custom-template-tags` for information on writing your own custom
template libraries.
Custom libraries and template inheritance

14
docs/topics/testing.txt
View File

@@ -1,5 +1,3 @@
.. _topics-testing:
===========================
Testing Django applications
===========================
@@ -342,7 +340,7 @@ For fine-grained control over the character encoding of your test
database, use the :setting:`TEST_CHARSET` option. If you're using
MySQL, you can also use the :setting:`TEST_COLLATION` option to
control the particular collation used by the test database. See the
:ref:`settings documentation <ref-settings>` for details of these
:doc:`settings documentation </ref/settings>` for details of these
advanced settings.
.. _topics-testing-masterslave:
@@ -751,7 +749,7 @@ arguments at time of construction:
.. versionadded:: 1.0
If your site uses Django's :ref:`authentication system<topics-auth>`
If your site uses Django's :doc:`authentication system</topics/auth>`
and you deal with logging in users, you can use the test client's
``login()`` method to simulate the effect of a user logging into the
site.
@@ -797,7 +795,7 @@ arguments at time of construction:
.. versionadded:: 1.0
If your site uses Django's :ref:`authentication system<topics-auth>`,
If your site uses Django's :doc:`authentication system</topics/auth>`,
the ``logout()`` method can be used to simulate the effect of a user
logging out of your site.
@@ -904,7 +902,7 @@ can access these properties as part of a test condition.
.. attribute:: Client.session
A dictionary-like object containing session information. See the
:ref:`session documentation<topics-http-sessions>` for full details.
:doc:`session documentation</topics/http/sessions>` for full details.
.. _Cookie module documentation: http://docs.python.org/library/cookie.html
@@ -1268,8 +1266,8 @@ E-mail services
.. versionadded:: 1.0
If any of your Django views send e-mail using :ref:`Django's e-mail
functionality <topics-email>`, you probably don't want to send e-mail each time
If any of your Django views send e-mail using :doc:`Django's e-mail
functionality </topics/email>`, you probably don't want to send e-mail each time
you run a test using that view. For this reason, Django's test runner
automatically redirects all Django-sent e-mail to a dummy outbox. This lets you
test every aspect of sending e-mail -- from the number of messages sent to the