From 4d7f9c9966de115adcd967edb4a37be74a1b626e Mon Sep 17 00:00:00 2001 From: Kosei Kitahara Date: Sun, 14 Oct 2012 00:16:24 +0900 Subject: [PATCH] Update internal link for sphinx 1.3.x. refs: #1 #2 --- docs/add_ons.txt | 28 +++------ docs/apache_auth.txt | 6 +- docs/api_stability.txt | 117 ++++++++++++++--------------------- docs/authentication.txt | 47 +++++--------- docs/cache.txt | 4 +- docs/contributing.txt | 9 +-- docs/db-api.txt | 26 +++----- docs/design_philosophies.txt | 4 +- docs/django-admin.txt | 12 +--- docs/email.txt | 20 ++---- docs/faq.txt | 46 ++++---------- docs/fastcgi.txt | 3 +- docs/flatpages.txt | 23 +++---- docs/forms.txt | 12 ++-- docs/generic_views.txt | 45 ++++++-------- docs/i18n.txt | 37 +++-------- docs/install.txt | 3 +- docs/legacy_databases.txt | 34 +++------- docs/middleware.txt | 18 ++---- docs/model-api.txt | 51 +++++---------- docs/modpython.txt | 3 +- docs/outputting_csv.txt | 10 +-- docs/outputting_pdf.txt | 4 +- docs/overview.txt | 7 +-- docs/redirects.txt | 20 ++---- docs/release_notes_0.95.txt | 10 ++- docs/request_response.txt | 10 +-- docs/serialization.txt | 24 +++---- docs/sessions.txt | 8 +-- docs/settings.txt | 86 +++++++++---------------- docs/sites.txt | 17 ++--- docs/static_files.txt | 10 +-- docs/syndication_feeds.txt | 23 ++----- docs/templates.txt | 14 ++--- docs/templates_python.txt | 41 ++++-------- docs/tutorial01.txt | 23 +++---- docs/tutorial02.txt | 17 ++--- docs/tutorial03.txt | 18 ++---- docs/tutorial04.txt | 18 ++---- docs/url_dispatch.txt | 16 ++--- 40 files changed, 297 insertions(+), 627 deletions(-) diff --git a/docs/add_ons.txt b/docs/add_ons.txt index 90c98b7176a6..d2e33c578644 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -12,18 +12,14 @@ admin ===== The automatic Django administrative interface. For more information, see -`Tutorial 2`_. - -.. _Tutorial 2: http://www.djangoproject.com/documentation/tutorial2/ +:doc:`Tutorial 2 `. auth ==== Django's authentication framework. -See the `authentication documentation`_. - -.. _authentication documentation: http://www.djangoproject.com/documentation/authentication/ +See the :doc:`authentication documentation `. comments ======== @@ -41,9 +37,7 @@ csrf A middleware for preventing Cross Site Request Forgeries -See the `csrf documentation`_. - -.. _csrf documentation: http://www.djangoproject.com/documentation/csrf/ +See the :doc:`csrf documentation `. humanize ======== @@ -115,9 +109,7 @@ flatpages A framework for managing simple "flat" HTML content in a database. -See the `flatpages documentation`_. - -.. _flatpages documentation: http://www.djangoproject.com/documentation/flatpages/ +See the :doc:`flatpages documentation `. markup ====== @@ -135,9 +127,7 @@ redirects A framework for managing redirects. -See the `redirects documentation`_. - -.. _redirects documentation: http://www.djangoproject.com/documentation/redirects/ +See the :doc:`redirects documentation `. sites ===== @@ -146,18 +136,14 @@ A light framework that lets you operate multiple Web sites off of the same database and Django installation. It gives you hooks for associating objects to one or more sites. -See the `sites documentation`_. - -.. _sites documentation: http://www.djangoproject.com/documentation/sites/ +See the :doc:`sites documentation `. syndication =========== A framework for generating syndication feeds, in RSS and Atom, quite easily. -See the `syndication documentation`_. - -.. _syndication documentation: http://www.djangoproject.com/documentation/syndication/ +See the :doc:`syndication documentation `. Other add-ons ============= diff --git a/docs/apache_auth.txt b/docs/apache_auth.txt index 72e084130517..9245bd378753 100644 --- a/docs/apache_auth.txt +++ b/docs/apache_auth.txt @@ -4,7 +4,7 @@ Authenticating against Django's user database from Apache Since keeping multiple authentication databases in sync is a common problem when dealing with Apache, you can configuring Apache to authenticate against Django's -`authentication system`_ directly. For example, you could: +:doc:`authentication system ` directly. For example, you could: * Serve media files directly from Apache only to authenticated users. @@ -49,7 +49,7 @@ location to users marked as staff members. You can use a set of Defaults to ``off``. ``DjangoPermissionName`` The name of a permission to require for - access. See `custom permissions`_ for + access. See :doc:`custom permissions ` for more information. By default no specific permission will be @@ -65,7 +65,5 @@ are equivalent:: SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonOption DJANGO_SETTINGS_MODULE mysite.settings -.. _authentication system: http://www.djangoproject.com/documentation/authentication/ .. _Subversion: http://subversion.tigris.org/ .. _mod_dav: http://httpd.apache.org/docs/2.0/mod/mod_dav.html -.. _custom permissions: http://www.djangoproject.com/documentation/authentication/#custom-permissions diff --git a/docs/api_stability.txt b/docs/api_stability.txt index a9d690473547..74691aab1730 100644 --- a/docs/api_stability.txt +++ b/docs/api_stability.txt @@ -14,16 +14,16 @@ In this context, stable means: - All the public APIs -- everything documented in the linked documents, and all methods that don't begin with an underscore -- will not be moved or renamed without providing backwards-compatible aliases. - + - If new features are added to these APIs -- which is quite possible -- they will not break or change the meaning of existing methods. In other words, "stable" does not (necessarily) mean "complete." - + - If, for some reason, an API declared stable must be removed or replaced, it will be declared deprecated but will remain in the API until at least version 1.1. Warnings will be issued when the deprecated method is called. - + - We'll only break backwards compatibility of these APIs if a bug or security hole makes it completely unavoidable. @@ -32,48 +32,48 @@ Stable APIs These APIs are stable: - - `Caching`_. - - - `Custom template tags and libraries`_ (with the possible exception for a + - :doc:`Caching `. + + - :doc:`Custom template tags and libraries ` (with the possible exception for a small change in the way templates are registered and loaded). - - - `Database lookup`_ (with the exception of validation; see below). - - - `django-admin utility`_. - - - `FastCGI integration`_. - - - `Flatpages`_. - - - `Generic views`_. - - - `Internationalization`_. - - - `Legacy database integration`_. - - - `Model definition`_ (with the exception of generic relations; see below). - - - `mod_python integration`_. - - - `Redirects`_. - - - `Request/response objects`_. - - - `Sending email`_. - - - `Sessions`_. - - - `Settings`_. - - - `Syndication`_. - - - `Template language`_ (with the exception of some possible disambiguation + + - :doc:`Database lookup ` (with the exception of validation; see below). + + - :doc:`django-admin utility `. + + - :doc:`FastCGI integration `. + + - :doc:`Flatpages `. + + - :doc:`Generic views `. + + - :doc:`Internationalization `. + + - :doc:`Legacy database integration `. + + - :doc:`Model definition ` (with the exception of generic relations; see below). + + - :doc:`mod_python integration `. + + - :doc:`Redirects `. + + - :doc:`Request/response objects `. + + - :doc:`Sending email `. + + - :doc:`Sessions `. + + - :doc:`Settings `. + + - :doc:`Syndication `. + + - :doc:`Template language ` (with the exception of some possible disambiguation of how tag arguments are passed to tags and filters). - - - `Transactions`_. - - - `URL dispatch`_. - + + - :doc:`Transactions `. + + - :doc:`URL dispatch `. + You'll notice that this list comprises the bulk of Django's APIs. That's right -- most of the changes planned between now and Django 1.0 are either under the hood, feature additions, or changes to a few select bits. A good estimate is @@ -82,12 +82,12 @@ that 90% of Django can be considered forwards-compatible at this point. That said, these APIs should *not* be considered stable, and are likely to change: - - `Forms and validation`_ will most likely be compeltely rewritten to + - :doc:`Forms and validation ` will most likely be compeltely rewritten to deemphasize Manipulators in favor of validation-aware models. - - `Serialization`_ is under heavy development; changes are likely. + - :doc:`Serialization ` is under heavy development; changes are likely. - - The `authentication`_ framework is changing to be far more flexible, and + - The :doc:`authentication ` framework is changing to be far more flexible, and API changes may be necessary. - Generic relations will most likely be moved out of core and into the @@ -96,28 +96,3 @@ change: - The comments framework, which is yet undocumented, will likely get a complete rewrite before Django 1.0. Even if the change isn't quite that drastic, - there will at least be moderate changes. - -.. _caching: http://www.djangoproject.com/documentation/cache/ -.. _custom template tags and libraries: http://www.djangoproject.com/documentation/templates_python/ -.. _database lookup: http://www.djangoproject.com/documentation/db_api/ -.. _django-admin utility: http://www.djangoproject.com/documentation/django_admin/ -.. _fastcgi integration: http://www.djangoproject.com/documentation/fastcgi/ -.. _flatpages: http://www.djangoproject.com/documentation/flatpages/ -.. _generic views: http://www.djangoproject.com/documentation/generic_views/ -.. _internationalization: http://www.djangoproject.com/documentation/i18n/ -.. _legacy database integration: http://www.djangoproject.com/documentation/legacy_databases/ -.. _model definition: http://www.djangoproject.com/documentation/model_api/ -.. _mod_python integration: http://www.djangoproject.com/documentation/modpython/ -.. _redirects: http://www.djangoproject.com/documentation/redirects/ -.. _request/response objects: http://www.djangoproject.com/documentation/request_response/ -.. _sending email: http://www.djangoproject.com/documentation/email/ -.. _sessions: http://www.djangoproject.com/documentation/sessions/ -.. _settings: http://www.djangoproject.com/documentation/settings/ -.. _syndication: http://www.djangoproject.com/documentation/syndication/ -.. _template language: http://www.djangoproject.com/documentation/templates/ -.. _transactions: http://www.djangoproject.com/documentation/transactions/ -.. _url dispatch: http://www.djangoproject.com/documentation/url_dispatch/ -.. _forms and validation: http://www.djangoproject.com/documentation/forms/ -.. _serialization: http://www.djangoproject.com/documentation/serialization/ -.. _authentication: http://www.djangoproject.com/documentation/authentication/ diff --git a/docs/authentication.txt b/docs/authentication.txt index d10dda28ef73..04eabb0773e6 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -80,7 +80,7 @@ Methods ``User`` objects have two many-to-many fields: ``groups`` and ``user_permissions``. ``User`` objects can access their related -objects in the same way as any other `Django model`_:: +objects in the same way as any other :doc:`Django model `:: myuser.objects.groups = [group_list] myuser.objects.groups.add(group, group,...) @@ -133,15 +133,12 @@ custom methods: * ``email_user(subject, message, from_email=None)`` -- Sends an e-mail to the user. If ``from_email`` is ``None``, Django uses the - `DEFAULT_FROM_EMAIL`_ setting. + :doc:`DEFAULT_FROM_EMAIL ` setting. * ``get_profile()`` -- Returns a site-specific profile for this user. Raises ``django.contrib.auth.models.SiteProfileNotAvailable`` if the current site doesn't allow profiles. -.. _Django model: http://www.djangoproject.com/documentation/model_api/ -.. _DEFAULT_FROM_EMAIL: http://www.djangoproject.com/documentation/settings/#default-from-email - Manager functions ~~~~~~~~~~~~~~~~~ @@ -249,11 +246,11 @@ Authentication in Web requests Until now, this document has dealt with the low-level APIs for manipulating authentication-related objects. On a higher level, Django can hook this -authentication framework into its system of `request objects`_. +authentication framework into its system of :doc:`request objects `. First, install the ``SessionMiddleware`` and ``AuthenticationMiddleware`` middlewares by adding them to your ``MIDDLEWARE_CLASSES`` setting. See the -`session documentation`_ for more information. +:doc:`session documentation ` for more information. Once you have those middlewares installed, you'll be able to access ``request.user`` in views. ``request.user`` will give you a ``User`` object @@ -266,9 +263,6 @@ previous section). You can tell them apart with ``is_authenticated()``, like so: else: # Do something for anonymous users. -.. _request objects: http://www.djangoproject.com/documentation/request_response/#httprequest-objects -.. _session documentation: http://www.djangoproject.com/documentation/sessions/ - How to log a user in -------------------- @@ -393,11 +387,11 @@ It's your responsibility to provide the login form in a template called template context variables: * ``form``: A ``FormWrapper`` object representing the login form. See the - `forms documentation`_ for more on ``FormWrapper`` objects. + :doc:`forms documentation ` for more on ``FormWrapper`` objects. * ``next``: The URL to redirect to after successful login. This may contain a query string, too. * ``site_name``: The name of the current ``Site``, according to the - ``SITE_ID`` setting. See the `site framework docs`_. + ``SITE_ID`` setting. See the :doc:`site framework docs `. If you'd prefer not to call the template ``registration/login.html``, you can pass the ``template_name`` parameter via the extra arguments to the view in @@ -430,9 +424,6 @@ block:: {% endblock %} -.. _forms documentation: http://www.djangoproject.com/documentation/forms/ -.. _site framework docs: http://www.djangoproject.com/documentation/sites/ - Limiting access to logged-in users that pass a test --------------------------------------------------- @@ -491,7 +482,7 @@ Example in Python 2.4 syntax:: Limiting access to generic views -------------------------------- -To limit access to a `generic view`_, write a thin wrapper around the view, +To limit access to a :doc:`generic view `, write a thin wrapper around the view, and point your URLconf to your wrapper instead of the generic view itself. For example:: @@ -501,8 +492,6 @@ For example:: def limited_object_detail(*args, **kwargs): return object_detail(*args, **kwargs) -.. _generic view: http://www.djangoproject.com/documentation/generic_views/ - Permissions =========== @@ -547,7 +536,7 @@ Custom permissions ------------------ To create custom permissions for a given model object, use the ``permissions`` -`model Meta attribute`_. +:doc:`model Meta attribute `. This example model creates three custom permissions:: @@ -563,8 +552,6 @@ This example model creates three custom permissions:: The only thing this does is create those extra permissions when you run ``syncdb``. -.. _model Meta attribute: http://www.djangoproject.com/documentation/model_api/#meta-options - API reference ------------- @@ -587,22 +574,20 @@ Methods ~~~~~~~ ``Permission`` objects have the standard data-access methods like any other -`Django model`_. +:doc:`Django model `. Authentication data in templates ================================ The currently logged-in user and his/her permissions are made available in the -`template context`_ when you use ``RequestContext``. +:doc:`template context ` when you use ``RequestContext``. .. admonition:: Technicality Technically, these variables are only made available in the template context if you use ``RequestContext`` *and* your ``TEMPLATE_CONTEXT_PROCESSORS`` setting contains ``"django.core.context_processors.auth"``, which is default. - For more, see the `RequestContext docs`_. - - .. _RequestContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-requestcontext + For more, see the :doc:`RequestContext docs `. Users ----- @@ -611,7 +596,7 @@ The currently logged-in user, either a ``User`` instance or an``AnonymousUser`` instance, is stored in the template variable ``{{ user }}``:: {% if user.is_authenticated %} -

Welcome, {{ user.username }}. Thanks for logging in.

+

Welcome, {{ user.username }}. Thanks for logging in.

{% else %}

Welcome, new user. Please log in.

{% endif %} @@ -648,8 +633,6 @@ Thus, you can check permissions in template ``{% if %}`` statements::

You don't have permission to do anything in the foo app.

{% endif %} -.. _template context: http://www.djangoproject.com/documentation/templates_python/ - Groups ====== @@ -696,7 +679,7 @@ a playlist:: context_instance=RequestContext(request)) When you use ``RequestContext``, the currently logged-in user and his/her -messages are made available in the `template context`_ as the template variable +messages are made available in the :doc:`template context ` as the template variable ``{{ messages }}``. Here's an example of template code that displays messages:: {% if messages %} @@ -711,9 +694,7 @@ Note that ``RequestContext`` calls ``get_and_delete_messages`` behind the scenes, so any messages will be deleted even if you don't display them. Finally, note that this messages framework only works with users in the user -database. To send messages to anonymous users, use the `session framework`_. - -.. _session framework: http://www.djangoproject.com/documentation/sessions/ +database. To send messages to anonymous users, use the :doc:`session framework `. Other authentication sources ============================ diff --git a/docs/cache.txt b/docs/cache.txt index 62fec289b9a6..56e2a9d30025 100644 --- a/docs/cache.txt +++ b/docs/cache.txt @@ -245,9 +245,7 @@ Additionally, ``CacheMiddleware`` 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 the `middleware documentation`_ for more on middleware. - -.. _`middleware documentation`: http://www.djangoproject.com/documentation/middleware/ +See the :doc:`middleware documentation `_ for more on middleware. The per-view cache ================== diff --git a/docs/contributing.txt b/docs/contributing.txt index 9d116cac10ee..26a74f5fb365 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -35,7 +35,7 @@ amount of overhead involved in working with any bug tracking system, so your help in keeping our ticket tracker as useful as possible is appreciated. In particular: - * **Do** read the FAQ_ to see if your issue might be a well-known question. + * **Do** read the :doc:`FAQ ` to see if your issue might be a well-known question. * **Do** `search the tracker`_ to see if your issue has already been filed. @@ -134,10 +134,9 @@ translated, here's what to do: * Join the `Django i18n mailing list`_ and introduce yourself. * Create and submit translations using the methods described in the - `i18n documentation`_. + :doc:`i18n documentation `. .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ -.. _i18n documentation: http://www.djangoproject.com/documentation/i18n/ Coding style ============ @@ -154,7 +153,7 @@ Please follow these coding standards when writing code for inclusion in Django: * Use ``InitialCaps`` for class names (or for factory functions that return classes). - * Mark all strings for internationalization; see the `i18n documentation`_ + * Mark all strings for internationalization; see the :doc:`i18n documentation ` for details. * In Django template code, put one (and only one) space between the curly @@ -431,12 +430,10 @@ requests for commit access are potential flame-war starters, and will be ignored .. _community page: http://www.djangoproject.com/community/ .. _ticket tracker: http://code.djangoproject.com/newticket .. _django-developers: http://groups.google.com/group/django-developers -.. _FAQ: http://www.djangoproject.com/documentation/faq/ .. _search the tracker: http://code.djangoproject.com/search .. _django-users: http://groups.google.com/group/django-users .. _`#django`: irc://irc.freenode.net/django .. _list of tickets with patches: http://code.djangoproject.com/report/12 .. _PEP 8: http://www.python.org/peps/pep-0008.html -.. _i18n documentation: http://www.djangoproject.com/documentation/i18n/ .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n .. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases diff --git a/docs/db-api.txt b/docs/db-api.txt index ce6bb0ab3bb0..37d1fae4a38a 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -2,12 +2,10 @@ Database API reference ====================== -Once you've created your `data models`_, Django automatically gives you a +Once you've created your :doc:`data models `, Django automatically gives you a database-abstraction API that lets you create, retrieve, update and delete objects. This document explains that API. -.. _`data models`: http://www.djangoproject.com/documentation/model_api/ - Throughout this reference, we'll refer to the following models, which comprise a weblog application:: @@ -83,9 +81,7 @@ There's no way to tell what the value of an ID will be before you call (For convenience, each model has an ``AutoField`` named ``id`` by default unless you explicitly specify ``primary_key=True`` on a field. See the -`AutoField documentation`_.) - -.. _AutoField documentation: http://www.djangoproject.com/documentation/model_api/#autofield +:doc:`AutoField documentation `.) Explicitly specifying auto-primary-key values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -715,12 +711,12 @@ The ``DoesNotExist`` exception inherits from A convenience method for creating an object and saving it all in one step. Thus:: p = Person.objects.create(first_name="Bruce", last_name="Springsteen") - + and:: p = Person(first_name="Bruce", last_name="Springsteen") p.save() - + are equivalent. ``get_or_create(**kwargs)`` @@ -1317,7 +1313,7 @@ precede the definition of any keyword arguments. For example:: See the `OR lookups examples page`_ for more examples. -.. _OR lookups examples page: http://www.djangoproject.com/documentation/models/or_lookups/ +.. _OR lookups examples page: models/or_lookups/ Related objects =============== @@ -1556,13 +1552,13 @@ Queries over related objects ---------------------------- Queries involving related objects follow the same rules as queries involving -normal value fields. When specifying the the value for a query to match, you -may use either an object instance itself, or the primary key value for the +normal value fields. When specifying the the value for a query to match, you +may use either an object instance itself, or the primary key value for the object. For example, if you have a Blog object ``b`` with ``id=5``, the following three queries would be identical:: - + Entry.objects.filter(blog=b) # Query using object instance Entry.objects.filter(blog=b.id) # Query using id from instance Entry.objects.filter(blog=5) # Query using id directly @@ -1638,7 +1634,7 @@ Note that in the case of identical date values, these methods will use the ID as a fallback check. This guarantees that no records are skipped or duplicated. For a full example, see the `lookup API sample model`_. -.. _lookup API sample model: http://www.djangoproject.com/documentation/models/lookup/ +.. _lookup API sample model: models/lookup/ get_FOO_filename() ------------------ @@ -1692,11 +1688,9 @@ The preferred way to do this is by giving your model custom methods or custom manager methods that execute queries. Although there's nothing in Django that *requires* database queries to live in the model layer, this approach keeps all your data-access logic in one place, which is smart from an code-organization -standpoint. For instructions, see `Executing custom SQL`_. +standpoint. For instructions, see :doc:`Executing custom 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, programming languages or database frameworks; there's nothing Django-specific about your database. - -.. _Executing custom SQL: http://www.djangoproject.com/documentation/model_api/#executing-custom-sql diff --git a/docs/design_philosophies.txt b/docs/design_philosophies.txt index 7fdc7ea01b65..15b4741cf78b 100644 --- a/docs/design_philosophies.txt +++ b/docs/design_philosophies.txt @@ -184,9 +184,7 @@ a common header, footer, navigation bar, etc. The Django template system should make it easy to store those elements in a single place, eliminating duplicate code. -This is the philosophy behind `template inheritance`_. - -.. _template inheritance: http://www.djangoproject.com/documentation/templates/#template-inheritance +This is the philosophy behind :doc:`template inheritance `. Be decoupled from HTML ---------------------- diff --git a/docs/django-admin.txt b/docs/django-admin.txt index eb7b2dccd61f..e1d2811164e0 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -51,17 +51,13 @@ adminindex [appname appname ...] Prints the admin-index template snippet for the given appnames. Use admin-index template snippets if you want to customize the look and feel of -your admin's index page. See `Tutorial 2`_ for more information. - -.. _Tutorial 2: http://www.djangoproject.com/documentation/tutorial2/ +your admin's index page. See :doc:`Tutorial 2 ` for more information. createcachetable [tablename] ---------------------------- Creates a cache table named ``tablename`` for use with the database cache -backend. See the `cache documentation`_ for more information. - -.. _cache documentation: http://www.djangoproject.com/documentation/cache/ +backend. See the :doc:`cache documentation ` for more information. dbshell ------- @@ -187,11 +183,9 @@ Serving static files with the development server By default, the development server doesn't serve any static files for your site (such as CSS files, images, things under ``MEDIA_ROOT_URL`` and so forth). If -you want to configure Django to serve static media, read the `serving static files`_ +you want to configure Django to serve static media, read the :doc:`serving static files ` documentation. -.. _serving static files: http://www.djangoproject.com/documentation/static_files/ - Turning off auto-reload ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/email.txt b/docs/email.txt index 37a4f38a5ed7..51f432db3e49 100644 --- a/docs/email.txt +++ b/docs/email.txt @@ -19,13 +19,11 @@ In two lines:: send_mail('Subject here', 'Here is the message.', 'from@example.com', ['to@example.com'], fail_silently=False) - + .. note:: The character set of email sent with ``django.core.mail`` will be set to - the value of your `DEFAULT_CHARSET setting`_. - -.. _DEFAULT_CHARSET setting: ../settings/#DEFAULT_CHARSET + the value of your :doc:`DEFAULT_CHARSET setting `. send_mail() =========== @@ -90,32 +88,26 @@ mail_admins() ============= ``django.core.mail.mail_admins()`` is a shortcut for sending an e-mail to the -site admins, as defined in the `ADMINS setting`_. Here's the definition:: +site admins, as defined in the :doc:`ADMINS setting `. Here's the definition:: mail_admins(subject, message, fail_silently=False) ``mail_admins()`` prefixes the subject with the value of the -`EMAIL_SUBJECT_PREFIX setting`_, which is ``"[Django] "`` by default. +:doc:`EMAIL_SUBJECT_PREFIX setting `, which is ``"[Django] "`` by default. -The "From:" header of the e-mail will be the value of the `SERVER_EMAIL setting`_. +The "From:" header of the e-mail will be the value of the :doc:`SERVER_EMAIL setting `. This method exists for convenience and readability. -.. _ADMINS setting: http://www.djangoproject.com/documentation/settings/#admins -.. _EMAIL_SUBJECT_PREFIX setting: http://www.djangoproject.com/documentation/settings/#email-subject-prefix -.. _SERVER_EMAIL setting: http://www.djangoproject.com/documentation/settings/#server-email - mail_managers() function ======================== ``django.core.mail.mail_managers()`` is just like ``mail_admins()``, except it -sends an e-mail to the site managers, as defined in the `MANAGERS setting`_. +sends an e-mail to the site managers, as defined in the :doc:`MANAGERS setting `. Here's the definition:: mail_managers(subject, message, fail_silently=False) -.. _MANAGERS setting: http://www.djangoproject.com/documentation/settings/#managers - Examples ======== diff --git a/docs/faq.txt b/docs/faq.txt index 36fb547cf1df..7830f539aa92 100644 --- a/docs/faq.txt +++ b/docs/faq.txt @@ -56,9 +56,7 @@ Django uses a "shared-nothing" architecture, which means you can add hardware at any level -- database servers, caching servers or Web/application servers. The framework cleanly separates components such as its database layer and -application layer. And it ships with a simple-yet-powerful `cache framework`_. - -.. _`cache framework`: http://www.djangoproject.com/documentation/cache/ +application layer. And it ships with a simple-yet-powerful :doc:`cache framework `. Who's behind this? ------------------ @@ -184,9 +182,7 @@ philosophies 100%. Like we said: We're picky. -We've documented our philosophies on the `design philosophies page`_. - -.. _design philosophies page: http://www.djangoproject.com/documentation/design_philosophies/ +We've documented our philosophies on the :doc:`design philosophies page `. Do you have any of those nifty "screencast" things? --------------------------------------------------- @@ -268,15 +264,12 @@ How do I get started? --------------------- #. `Download the code`_. - #. Install Django (read the `installation guide`_). - #. Walk through the tutorial_. - #. Check out the rest of the documentation_, and `ask questions`_ if you + #. Install Django (read the :doc:`installation guide `). + #. Walk through the :doc:`tutorial `. + #. Check out the rest of the :doc:`documentation `, and `ask questions`_ if you run into trouble. .. _`Download the code`: http://www.djangoproject.com/download/ -.. _`installation guide`: http://www.djangoproject.com/documentation/install/ -.. _tutorial: http://www.djangoproject.com/documentation/tutorial1/ -.. _documentation: http://www.djangoproject.com/documentation/ .. _ask questions: http://www.djangoproject.com/community/ How do I fix the "install a later version of setuptools" error? @@ -314,7 +307,7 @@ Do I have to use mod_python? Although we recommend mod_python for production use, you don't have to use it, thanks to the fact that Django uses an arrangement called WSGI_. Django can talk to any WSGI-enabled server. The most common non-mod_python deployment -setup is FastCGI. See `How to use Django with FastCGI`_ for full information. +setup is FastCGI. See :doc:`How to use Django with FastCGI ` for full information. Also, see the `server arrangements wiki page`_ for other deployment strategies. @@ -322,7 +315,6 @@ If you just want to play around and develop things on your local computer, use the development Web server that comes with Django. Things should Just Work. .. _WSGI: http://www.python.org/peps/pep-0333.html -.. _How to use Django with FastCGI: http://www.djangoproject.com/documentation/fastcgi/ .. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements How do I install mod_python on Windows? @@ -447,9 +439,7 @@ SELECTs, etc. Each time your app hits the database, the query will be recorded. Can I use Django with a pre-existing database? ---------------------------------------------- -Yes. See `Integrating with a legacy database`_. - -.. _`Integrating with a legacy database`: http://www.djangoproject.com/documentation/legacy_databases/ +Yes. See :doc:`Integrating with a legacy database `. If I make changes to a model, how do I update the database? ----------------------------------------------------------- @@ -484,7 +474,7 @@ How do I add database-specific options to my CREATE TABLE statements, such as sp We try to avoid adding special cases in the Django code to accomodate all the database-specific options such as table type, etc. If you'd like to use any of -these options, create an `SQL initial data file`_ that contains ``ALTER TABLE`` +these options, create an :doc:`SQL initial data file ` that contains ``ALTER TABLE`` statements that do what you want to do. The initial data files are executed in your database after the ``CREATE TABLE`` statements. @@ -493,11 +483,9 @@ type, create an initial data file and put something like this in it:: ALTER TABLE myapp_mytable ENGINE=MyISAM; -As explained in the `SQL initial data file`_ documentation, this SQL file can +As explained in the :doc:`SQL initial data file ` documentation, this SQL file can contain arbitrary SQL, so you can make any sorts of changes you need to make. -.. _SQL initial data file: http://www.djangoproject.com/documentation/model_api/#providing-initial-sql-data - Why is Django leaking memory? ----------------------------- @@ -549,9 +537,7 @@ How can I prevent the cache middleware from caching the admin site? ------------------------------------------------------------------- Set the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting to ``True``. See the -`cache documentation`_ for more information. - -.. _cache documentation: ../cache/#the-per-site-cache +:doc:`cache documentation ` for more information. How do I automatically set a field's value to the user who last edited the object in the admin? ----------------------------------------------------------------------------------------------- @@ -574,11 +560,9 @@ See the answer to the previous question. My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_python. --------------------------------------------------------------------------------------------------------------------------- -See `serving the admin files`_ in the "How to use Django with mod_python" +See :doc:`serving the admin files ` in the "How to use Django with mod_python" documentation. -.. _serving the admin files: http://www.djangoproject.com/documentation/modpython/#serving-the-admin-files - My "list_filter" contains a ManyToManyField, but the filter doesn't display. ---------------------------------------------------------------------------- @@ -613,9 +597,7 @@ We like it, but if you don't agree, you can modify the admin site's presentation by editing the CSS stylesheet and/or associated image files. The site is built using semantic HTML and plenty of CSS hooks, so any changes you'd like to make should be possible by editing the stylesheet. We've got a -`guide to the CSS used in the admin`_ to get you started. - -.. _`guide to the CSS used in the admin`: http://www.djangoproject.com/documentation/admin_css/ +:doc:`guide to the CSS used in the admin ` to get you started. How do I create users without having to edit password hashes? ------------------------------------------------------------- @@ -625,11 +607,9 @@ moment it requires you to edit password hashes manually. (Passwords are hashed using one-way hash algorithms for security; there's currently no Web interface for changing passwords by entering the actual password rather than the hash.) -To create a user, you'll have to use the Python API. See `creating users`_ for +To create a user, you'll have to use the Python API. See :doc:`creating users ` for full info. -.. _creating users: http://www.djangoproject.com/documentation/authentication/#creating-users - Contributing code ================= diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt index 41d50d97a180..af409fab1ebf 100644 --- a/docs/fastcgi.txt +++ b/docs/fastcgi.txt @@ -2,7 +2,7 @@ How to use Django with FastCGI ============================== -Although the `current preferred setup`_ for running Django is Apache_ with +Although the :doc:`current preferred setup ` for running Django is Apache_ with `mod_python`_, many people use shared hosting, on which FastCGI is the only viable option. In some setups, FastCGI also allows better security -- and, possibly, better performance -- than mod_python. @@ -17,7 +17,6 @@ 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, persistent process. -.. _current preferred setup: http://www.djangoproject.com/documentation/modpython/ .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _mod_perl: http://perl.apache.org/ diff --git a/docs/flatpages.txt b/docs/flatpages.txt index 06979f7a9a3c..24a292f11737 100644 --- a/docs/flatpages.txt +++ b/docs/flatpages.txt @@ -24,14 +24,11 @@ Installation To install the flatpages app, follow these steps: - 1. Add ``'django.contrib.flatpages'`` to your INSTALLED_APPS_ setting. + 1. Add ``'django.contrib.flatpages'`` to your :doc:`INSTALLED_APPS ` setting. 2. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'`` - to your MIDDLEWARE_CLASSES_ setting. + to your :doc:`MIDDLEWARE_CLASSES ` setting. 3. Run the command ``manage.py syncdb``. -.. _INSTALLED_APPS: http://www.djangoproject.com/documentation/settings/#installed-apps -.. _MIDDLEWARE_CLASSES: http://www.djangoproject.com/documentation/settings/#middleware-classes - How it works ============ @@ -43,14 +40,14 @@ that simply maps a URL to a title and bunch of text content. The ``FlatpageFallbackMiddleware`` does all of the work. Each time any Django application raises a 404 error, this middleware checks the flatpages database for the requested URL as a last resort. Specifically, it checks for a flatpage -with the given URL with a site ID that corresponds to the SITE_ID_ setting. +with the given URL with a site ID that corresponds to the :doc:`SITE_ID ` setting. If it finds a match, it follows this algorithm: * If the flatpage has a custom template, it loads that template. Otherwise, it loads the template ``flatpages/default``. * It passes that template a single context variable, ``flatpage``, which is - the flatpage object. It uses RequestContext_ in rendering the template. + the flatpage object. It uses :doc:`RequestContext ` in rendering the template. If it doesn't find a match, the request continues to be processed as usual. @@ -61,11 +58,7 @@ Note that the order of ``MIDDLEWARE_CLASSES`` matters. Generally, you can put ``FlatpageFallbackMiddleware`` at the end of the list, because it's a last resort. -For more on middleware, read the `middleware docs`_. - -.. _SITE_ID: http://www.djangoproject.com/documentation/settings/#site-id -.. _RequestContext: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext -.. _middleware docs: http://www.djangoproject.com/documentation/middleware/ +For more on middleware, read the :doc:`middleware docs `. How to add, change and delete flatpages ======================================= @@ -80,13 +73,11 @@ other object in the system. Via the Python API ------------------ -Flatpages are represented by a standard `Django model`_, which lives in +Flatpages are represented by a standard :doc:`Django model `, which lives in `django/contrib/flatpages/models.py`_. You can access flatpage objects via the -`Django database API`_. +:doc:`Django database API `. -.. _Django model: http://www.djangoproject.com/documentation/model_api/ .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py -.. _Django database API: http://www.djangoproject.com/documentation/db_api/ Flatpage templates ================== diff --git a/docs/forms.txt b/docs/forms.txt index 67408f3c5d37..2af7231aded9 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -9,7 +9,7 @@ code. It is, and this document explains how the framework works. .. admonition:: A note to the lazy If all you want to do is present forms for a user to create and/or - update a given object, you may be able to use `generic views`_. + update a given object, you may be able to use :doc:`generic views `. We'll take a top-down approach to examining Django's form validation framework, because much of the time you won't need to use the lower-level APIs. Throughout @@ -350,7 +350,7 @@ identical and could in fact be collapsed into a single view. This is left as an exercise for said programmer. (However, the even-more-astute programmer will take heed of the note at the top -of this document and check out the `generic views`_ documentation if all she +of this document and check out the :doc:`generic views ` documentation if all she wishes to do is this type of simple create/update.) Custom forms and manipulators @@ -404,7 +404,7 @@ Here's a simple function that might drive the above form:: errors = new_data = {} form = forms.FormWrapper(manipulator, new_data, errors) return render_to_response('contact_form.html', {'form': form}) - + ``FileField`` and ``ImageField`` special cases ============================================== @@ -615,9 +615,5 @@ fails. If no message is passed in, a default message is used. a file path to the location of the schema and an optional root element (which is wrapped around the XML fragment before validation, if supplied). At validation time, the XML fragment is validated against the schema using - the executable specified in the ``JING_PATH`` setting (see the settings_ + the executable specified in the ``JING_PATH`` setting (see the :doc:`settings ` document for more details). - -.. _`generic views`: http://www.djangoproject.com/documentation/generic_views/ -.. _`models API`: http://www.djangoproject.com/documentation/model_api/ -.. _settings: http://www.djangoproject.com/documentation/settings/ diff --git a/docs/generic_views.txt b/docs/generic_views.txt index aab878467f95..0f18ed7cbaae 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -10,7 +10,7 @@ an object without actually needing to write any Python code. Django's generic views contain the following: * A set of views for doing list/detail interfaces (for example, - Django's `documentation index`_ and `detail pages`_). + Django's :doc:`documentation index ` and :doc:`detail pages `). * A set of views for year/month/day archive pages and associated detail and "latest" pages (for example, the Django weblog's year_, @@ -18,8 +18,6 @@ Django's generic views contain the following: * A set of views for creating, editing, and deleting objects. -.. _`documentation index`: http://www.djangoproject.com/documentation/ -.. _`detail pages`: http://www.djangoproject.com/documentation/faq/ .. _year: http://www.djangoproject.com/weblog/2005/ .. _month: http://www.djangoproject.com/weblog/2005/jul/ .. _day: http://www.djangoproject.com/weblog/2005/jul/20/ @@ -59,7 +57,7 @@ arguments may either come from the URL pattern (as ``month``, ``day``, ``queryset``, ``date_field``, etc.). Most generic views require the ``queryset`` key, which is a ``QuerySet`` -instance; see the `database API docs`_ for more information about ``Queryset`` +instance; see the :doc:`database API docs ` for more information about ``Queryset`` objects. Most views also take an optional ``extra_context`` dictionary that you can use @@ -71,8 +69,6 @@ are first evaluated, so if you want to pass in a QuerySet via ``extra_context`` that is always fresh you need to wrap it in a function or lambda that returns the QuerySet. -.. _database API docs: http://www.djangoproject.com/documentation/db_api/ - "Simple" generic views ====================== @@ -181,7 +177,7 @@ a date in the *future* are not included unless you set ``allow_future`` to default, this is ``False``. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``mimetype``: The MIME type to use for the resulting document. Defaults to the value of the ``DEFAULT_MIME_TYPE`` setting. @@ -215,8 +211,6 @@ In addition to ``extra_context``, the template's context will be: by ``date_field``. For example, if ``num_latest`` is ``10``, then ``latest`` will be a list of the latest 10 objects in ``queryset``. -.. _RequestContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext - ``django.views.generic.date_based.archive_year`` ------------------------------------------------ @@ -255,7 +249,7 @@ to ``True``. default, this is ``False``. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. The @@ -349,7 +343,7 @@ date in the *future* are not displayed unless you set ``allow_future`` to default, this is ``False``. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. The @@ -430,7 +424,7 @@ in the *future* are not displayed unless you set ``allow_future`` to ``True``. default, this is ``True``. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. The @@ -515,7 +509,7 @@ you set ``allow_future`` to ``True``. default, this is ``False``. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. The @@ -627,7 +621,7 @@ future, the view will throw a 404 error by default, unless you set just before rendering the template. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. @@ -699,7 +693,7 @@ A page representing a list of objects. default, this is ``False``. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. The @@ -813,7 +807,7 @@ A page representing an individual object. just before rendering the template. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. @@ -866,7 +860,7 @@ automatic manipulators that come with Django models. * ``login_required``: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the - Django `authentication system`_. By default, this is ``False``. + Django :doc:`authentication system `. By default, this is ``False``. If this is ``True``, and a non-logged-in user attempts to visit this page or save the form, Django will redirect the request to ``/accounts/login/``. @@ -883,7 +877,7 @@ automatic manipulators that come with Django models. just before rendering the template. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. **Template name:** @@ -905,12 +899,9 @@ In addition to ``extra_context``, the template's context will be:

{{ form.address }}

- See the `manipulator and formfield documentation`_ for more information + See the :doc:`manipulator and formfield documentation ` for more information about using ``FormWrapper`` objects in templates. -.. _authentication system: http://www.djangoproject.com/documentation/authentication/ -.. _manipulator and formfield documentation: http://www.djangoproject.com/documentation/forms/ - ``django.views.generic.create_update.update_object`` ---------------------------------------------------- @@ -945,7 +936,7 @@ object. This uses the automatic manipulators that come with Django models. * ``login_required``: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the - Django `authentication system`_. By default, this is ``False``. + Django :doc:`authentication system `. By default, this is ``False``. If this is ``True``, and a non-logged-in user attempts to visit this page or save the form, Django will redirect the request to ``/accounts/login/``. @@ -962,7 +953,7 @@ object. This uses the automatic manipulators that come with Django models. just before rendering the template. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. @@ -987,7 +978,7 @@ In addition to ``extra_context``, the template's context will be:

{{ form.address }}

- See the `manipulator and formfield documentation`_ for more information + See the :doc:`manipulator and formfield documentation ` for more information about using ``FormWrapper`` objects in templates. * ``object``: The original object being edited. This variable's name @@ -1026,7 +1017,7 @@ contain a form that POSTs to the same URL. * ``login_required``: A boolean that designates whether a user must be logged in, in order to see the page and save changes. This hooks into the - Django `authentication system`_. By default, this is ``False``. + Django :doc:`authentication system `. By default, this is ``False``. If this is ``True``, and a non-logged-in user attempts to visit this page or save the form, Django will redirect the request to ``/accounts/login/``. @@ -1043,7 +1034,7 @@ contain a form that POSTs to the same URL. just before rendering the template. * ``context_processors``: A list of template-context processors to apply to - the view's template. See the `RequestContext docs`_. + the view's template. See the :doc:`RequestContext docs `. * ``template_object_name``: Designates the name of the template variable to use in the template context. By default, this is ``'object'``. diff --git a/docs/i18n.txt b/docs/i18n.txt index e12900c2f9a2..e336521494a2 100644 --- a/docs/i18n.txt +++ b/docs/i18n.txt @@ -50,9 +50,7 @@ use internationalization, you should take the two seconds to set ``False``, then Django will make some optimizations so as not to load the internationalization machinery. -See the `documentation for USE_I18N`_. - -.. _documentation for USE_I18N: http://www.djangoproject.com/documentation/settings/#use-i18n +See the :doc:`documentation for USE_I18N `. How to specify translation strings ================================== @@ -161,7 +159,7 @@ If you don't like the verbose name ``gettext_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 `Django models`_. And it's a good idea to add +Always use lazy translations in :doc:`Django models `. And it's a good idea to add translations for the field names and table names, too. This means writing explicit ``verbose_name`` and ``verbose_name_plural`` options in the ``Meta`` class, though:: @@ -174,8 +172,6 @@ class, though:: verbose_name = _('my thing') verbose_name_plural = _('mythings') -.. _Django models: http://www.djangoproject.com/documentation/model_api/ - Pluralization ~~~~~~~~~~~~~ @@ -196,7 +192,7 @@ translation languages as the ``count`` variable). In template code ---------------- -Using translations in `Django templates`_ uses two template tags and a slightly +Using translations in :doc:`Django 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. @@ -273,8 +269,6 @@ translation string. Example:: In this case, both the tag and the filter will see the already-translated string, so they don't need to be aware of translations. -.. _Django templates: http://www.djangoproject.com/documentation/templates_python/ - How to create language files ============================ @@ -390,11 +384,9 @@ That's it. Your translations are ready for use. .. admonition:: A note to translators If you've created a translation in a language Django doesn't yet support, - please let us know! See `Submitting and maintaining translations`_ for + please let us know! See :doc:`Submitting and maintaining translations ` for the steps to take. - .. _Submitting and maintaining translations: http://www.djangoproject.com/documentation/contributing/ - How Django discovers language preference ======================================== @@ -406,7 +398,7 @@ Behind the scenes, Django has a very flexible model of deciding which language should be used -- installation-wide, for a particular user, or both. To set an installation-wide language preference, set ``LANGUAGE_CODE`` in your -`settings file`_. Django uses this language as the default translation -- the +:doc:`settings file `. Django uses this language as the default translation -- the final attempt if no other translator finds a translation. If all you want to do is run Django with your native language, and a language @@ -434,13 +426,13 @@ For example, your ``MIDDLEWARE_CLASSES`` might look like this:: 'django.middleware.common.CommonMiddleware', ) -(For more on middleware, see the `middleware documentation`_.) +(For more on middleware, see the :doc:`middleware documentation `.) ``LocaleMiddleware`` tries to determine the user's language preference by following this algorithm: * First, it looks for a ``django_language`` key in the the current user's - `session`_. + :doc:`session `. * Failing that, it looks for a cookie called ``django_language``. * Failing that, it looks at the ``Accept-Language`` HTTP header. This header is sent by your browser and tells the server which language(s) you @@ -457,7 +449,7 @@ Notes: Django uses the base language. For example, if a user specifies ``de-at`` (Austrian German) but Django only has ``de`` available, Django uses ``de``. - * Only languages listed in the `LANGUAGES setting`_ can be selected. If + * Only languages listed in the :doc:`LANGUAGES setting ` can be selected. If you want to restrict the language selection to a subset of provided languages (because your application doesn't provide all those languages), set ``LANGUAGES`` to a list of languages. For example:: @@ -471,8 +463,6 @@ Notes: selection to German and English (and any sublanguage, like de-ch or en-us). - .. _LANGUAGES setting: http://www.djangoproject.com/documentation/settings/#languages - * If you define a custom ``LANGUAGES`` setting, as explained in the previous bullet, it's OK to mark the languages as translation strings -- but use a "dummy" ``gettext()`` function, not the one in @@ -516,7 +506,7 @@ Notes: is identical to the format strings used by the ``now`` template tag. Once ``LocaleMiddleware`` determines the user's preference, it makes this -preference available as ``request.LANGUAGE_CODE`` for each `request object`_. +preference available as ``request.LANGUAGE_CODE`` for each :doc:`request object `. Feel free to read this value in your view code. Here's a simple example:: def hello_world(request, count): @@ -529,11 +519,6 @@ Note that, with static (middleware-less) translation, the language is in ``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's in ``request.LANGUAGE_CODE``. -.. _settings file: http://www.djangoproject.com/documentation/settings/ -.. _middleware documentation: http://www.djangoproject.com/documentation/middleware/ -.. _session: http://www.djangoproject.com/documentation/sessions/ -.. _request object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects - The ``set_language`` redirect view ================================== @@ -592,14 +577,12 @@ message file. The choice is yours. .. note:: If you're using manually configured settings, as described in the - `settings documentation`_, the ``locale`` directory in the project + :doc:`settings documentation `, the ``locale`` directory in the project directory will not be examined, since Django loses the ability to work out the location of the project directory. (Django normally uses the location of the settings file to determine this, and a settings file doesn't exist if you're manually configuring your settings.) -.. _settings documentation: http://www.djangoproject.com/documentation/settings/#using-settings-without-the-django-settings-module-environment-variable - All message file repositories are structured the same way. They are: * ``$APPPATH/locale//LC_MESSAGES/django.(po|mo)`` diff --git a/docs/install.txt b/docs/install.txt index fb1bd73122fb..fca0eb3e1038 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -27,7 +27,7 @@ the life of an Apache process, which leads to significant performance gains over other server arrangements. Make sure you have Apache installed, with the mod_python module activated. Django requires Apache 2.x and mod_python 3.x. -See `How to use Django with mod_python`_ for information on how to configure +See :doc:`How to use Django with mod_python ` for information on how to configure mod_python once you have it installed. If you can't use mod_python for some reason, fear not: Django follows the WSGI_ @@ -38,7 +38,6 @@ each platform. .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _WSGI: http://www.python.org/peps/pep-0333.html -.. _How to use Django with mod_python: http://www.djangoproject.com/documentation/modpython/ .. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements Get your database running diff --git a/docs/legacy_databases.txt b/docs/legacy_databases.txt index 66cb1a2ef4d4..35f919f1c980 100644 --- a/docs/legacy_databases.txt +++ b/docs/legacy_databases.txt @@ -7,33 +7,21 @@ possible to integrate it into legacy databases. Django includes a couple of utilities to automate as much of this process as possible. This document assumes you know the Django basics, as covered in the -`official tutorial`_. - -.. _official tutorial: http://www.djangoproject.com/documentation/tutorial1/ +:doc:`official tutorial `. Give Django your database parameters ==================================== You'll need to tell Django what your database connection parameters are, and what the name of the database is. Do that by editing these settings in your -`settings file`_: - - * `DATABASE_NAME` - * `DATABASE_ENGINE`_ - * `DATABASE_USER`_ - * `DATABASE_PASSWORD`_ - * `DATABASE_NAME`_ - * `DATABASE_HOST`_ - * `DATABASE_PORT`_ - -.. _settings file: http://www.djangoproject.com/documentation/settings/ -.. _DATABASE_NAME: http://www.djangoproject.com/documentation/settings/#database-name -.. _DATABASE_ENGINE: http://www.djangoproject.com/documentation/settings/#database-engine -.. _DATABASE_USER: http://www.djangoproject.com/documentation/settings/#database-user -.. _DATABASE_PASSWORD: http://www.djangoproject.com/documentation/settings/#database-password -.. _DATABASE_NAME: http://www.djangoproject.com/documentation/settings/#database-name -.. _DATABASE_HOST: http://www.djangoproject.com/documentation/settings/#database-host -.. _DATABASE_PORT: http://www.djangoproject.com/documentation/settings/#database-port +:doc:`settings file `: + + * DATABASE_ENGINE + * DATABASE_USER + * DATABASE_PASSWORD + * DATABASE_NAME + * DATABASE_HOST + * DATABASE_PORT Auto-generate the models ======================== @@ -48,14 +36,12 @@ Save this as a file by using standard Unix output redirection:: django-admin.py inspectdb --settings=path.to.settings > models.py This feature is meant as a shortcut, not as definitive model generation. See -the `django-admin.py documentation`_ for more information. +the :doc:`django-admin.py documentation ` for more information. Once you've cleaned up your models, name the file ``models.py`` and put it in the Python package that holds your app. Then add the app to your ``INSTALLED_APPS`` setting. -.. _django-admin.py documentation: http://www.djangoproject.com/documentation/django_admin/ - Install the core Django tables ============================== diff --git a/docs/middleware.txt b/docs/middleware.txt index bad00fd890c2..dab4c71a875f 100644 --- a/docs/middleware.txt +++ b/docs/middleware.txt @@ -45,9 +45,7 @@ django.middleware.cache.CacheMiddleware Enables site-wide cache. If this is enabled, each Django-powered page will be cached for as long as the ``CACHE_MIDDLEWARE_SECONDS`` setting defines. See -the `cache documentation`_. - -.. _`cache documentation`: http://www.djangoproject.com/documentation/cache/#the-per-site-cache +the :doc:`cache documentation `. django.middleware.common.CommonMiddleware ----------------------------------------- @@ -63,7 +61,7 @@ Adds a few conveniences for perfectionists: last component in the path contains a period. So ``foo.com/bar`` is redirected to ``foo.com/bar/``, but ``foo.com/bar/file.txt`` is passed through unchanged. - + If ``PREPEND_WWW`` is ``True``, URLs that lack a leading "www." will be redirected to the same URL with a leading "www." @@ -104,17 +102,13 @@ Also removes the content from any response to a HEAD request and sets the django.contrib.sessions.middleware.SessionMiddleware ---------------------------------------------------- -Enables session support. See the `session documentation`_. - -.. _`session documentation`: http://www.djangoproject.com/documentation/sessions/ +Enables session support. See the :doc:`session documentation `. django.contrib.auth.middleware.AuthenticationMiddleware ------------------------------------------------------- Adds the ``user`` attribute, representing the currently-logged-in user, to -every incoming ``HttpRequest`` object. See `Authentication in Web requests`_. - -.. _Authentication in Web requests: http://www.djangoproject.com/documentation/authentication/#authentication-in-web-requests +every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests `. django.middleware.transaction.TransactionMiddleware --------------------------------------------------- @@ -128,9 +122,7 @@ running outside of it run with commit-on-save - the default Django behavior. Middleware modules running inside it (coming later in the stack) will be under the same transaction control as the view functions. -See the `transaction management documentation`_. - -.. _`transaction management documentation`: http://www.djangoproject.com/documentation/transactions/ +See the :doc:`transaction management documentation `. Writing your own middleware =========================== diff --git a/docs/model-api.txt b/docs/model-api.txt index c369508c6577..eb9ae5bccc82 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -15,14 +15,13 @@ The basics: * Metadata used for Django's admin site goes into an inner class named ``Admin``. * With all of this, Django gives you an automatically-generated - database-access API, which is explained in the `Database API reference`_. + database-access API, which is explained in the :doc:`Database API reference `. A companion to this document is the `official repository of model examples`_. (In the Django source distribution, these examples are in the ``tests/modeltests`` directory.) -.. _Database API reference: http://www.djangoproject.com/documentation/db_api/ -.. _official repository of model examples: http://www.djangoproject.com/documentation/models/ +.. _official repository of model examples: ../models/ Quick example ============= @@ -55,9 +54,7 @@ Some technical notes: overriden. See `Automatic primary key fields`_ below. * 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 `settings file`_. - -.. _settings file: http://www.djangoproject.com/documentation/settings/ + backend specified in your :doc:`settings file `. Fields ====== @@ -599,12 +596,10 @@ Like ``unique_for_date`` and ``unique_for_month``. A list of extra validators to apply to the field. Each should be a callable that takes the parameters ``field_data, all_data`` and raises ``django.core.validators.ValidationError`` for errors. (See the -`validator docs`_.) +:doc:`validator docs `.) Django comes with quite a few validators. They're in ``django.core.validators``. -.. _validator docs: http://www.djangoproject.com/documentation/forms/#validators - Verbose field names ------------------- @@ -691,7 +686,7 @@ You can, of course, call the field whatever you want. For example:: See the `Many-to-one relationship model example`_ for a full example. -.. _Many-to-one relationship model example: http://www.djangoproject.com/documentation/models/many_to_one/ +.. _Many-to-one relationship model example: ../models/many_to_one/ ``ForeignKey`` fields take a number of extra arguments for defining how the relationship should work. All are optional: @@ -708,7 +703,7 @@ relationship should work. All are optional: fieldsets. ``limit_choices_to`` A dictionary of lookup arguments and values (see - the `Database API reference`_) that limit the + the :doc:`Database API reference `) that limit the available admin choices for this object. Use this with ``models.LazyDate`` to limit choices of objects by date. For example:: @@ -760,7 +755,7 @@ relationship should work. All are optional: ``related_name`` The name to use for the relation from the related object back to this one. See the - `related objects documentation`_ for a full + :doc:`related objects documentation ` for a full explanation and example. ``to_field`` The field on the related object that the relation @@ -768,9 +763,6 @@ relationship should work. All are optional: the related object. ======================= ============================================================ -.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/ -.. _related objects documentation: http://www.djangoproject.com/documentation/db_api/#related-objects - Many-to-many relationships ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -815,7 +807,7 @@ set up above, the ``Pizza`` admin form would let users select the toppings. See the `Many-to-many relationship model example`_ for a full example. -.. _Many-to-many relationship model example: http://www.djangoproject.com/documentation/models/many_to_many/ +.. _Many-to-many relationship model example: ../models/many_to_many/ ``ManyToManyField`` objects take a number of extra arguments for defining how the relationship should work. All are optional: @@ -888,7 +880,7 @@ as a read-only field when you edit an object in the admin interface: See the `One-to-one relationship model example`_ for a full example. -.. _One-to-one relationship model example: http://www.djangoproject.com/documentation/models/one_to_one/ +.. _One-to-one relationship model example: ../models/one_to_one/ Meta options ============ @@ -930,9 +922,7 @@ Example:: get_latest_by = "order_date" -See the `docs for latest()`_ for more. - -.. _docs for latest(): http://www.djangoproject.com/documentation/db_api/#latest-field-name-none +See the :doc:`docs for latest() ` for more. ``order_with_respect_to`` ------------------------- @@ -978,7 +968,7 @@ See `Specifying ordering`_ for more examples. Note that, regardless of how many fields are in ``ordering``, the admin site uses only the first field. -.. _Specifying ordering: http://www.djangoproject.com/documentation/models/ordering/ +.. _Specifying ordering: ../models/ordering/ ``permissions`` --------------- @@ -1309,9 +1299,7 @@ The value should be either ``True`` or ``False``. Default is ``False``. Note that Django will use ``select_related()``, regardless of this setting, if one of the ``list_display`` fields is a ``ForeignKey``. -For more on ``select_related()``, see `the select_related() docs`_. - -.. _the select_related() docs: http://www.djangoproject.com/documentation/db_api/#select-related +For more on ``select_related()``, see :doc:`the select_related() docs `. ``ordering`` ------------ @@ -1374,12 +1362,10 @@ 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 the `Retrieving objects`_ +The way ``Manager`` classes work is documented in the :doc:`Retrieving objects ` section of the database API docs, but this section specifically touches on model options that customize ``Manager`` behavior. -.. _Retrieving objects: http://www.djangoproject.com/documentation/db_api/#retrieving-objects - Manager names ------------- @@ -1660,15 +1646,14 @@ the sake of consistency and sanity.) A final note: If all you want to do is a custom ``WHERE`` clause, you can just just the ``where``, ``tables`` and ``params`` arguments to the standard lookup -API. See `Other lookup options`_. +API. See :doc:`Other lookup options `. .. _Python DB-API: http://www.python.org/peps/pep-0249.html -.. _Other lookup options: http://www.djangoproject.com/documentation/db_api/#extra-params-select-where-tables Overriding default model methods -------------------------------- -As explained in the `database API docs`_, each model gets a few methods +As explained in the :doc:`database API docs `, each model gets a few methods automatically -- most notably, ``save()`` and ``delete()``. You can override these methods to alter behavior. @@ -1696,8 +1681,6 @@ You can also prevent saving:: else: super(Blog, self).save() # Call the "real" save() method. -.. _database API docs: http://www.djangoproject.com/documentation/db_api/ - Models across files =================== @@ -1754,7 +1737,7 @@ piped directly into the database after all of the models' table-creation statements have been executed. The SQL files are read by the ``sqlinitialdata``, ``sqlreset``, ``sqlall`` and -``reset`` commands in ``manage.py``. Refer to the `manage.py documentation`_ +``reset`` commands in ``manage.py``. Refer to the :doc:`manage.py documentation ` for more information. Note that if you have multiple SQL data files, there's no guarantee of the @@ -1762,8 +1745,6 @@ order in which they're executed. The only thing you can assume is that, by the time your custom data files are executed, all the database tables already will have been created. -.. _`manage.py documentation`: http://www.djangoproject.com/documentation/django_admin/#sqlinitialdata-appname-appname - Database-backend-specific SQL data ---------------------------------- diff --git a/docs/modpython.txt b/docs/modpython.txt index b88874d3d3e9..f255fee780ae 100644 --- a/docs/modpython.txt +++ b/docs/modpython.txt @@ -13,14 +13,13 @@ other server arrangements. Django requires Apache 2.x and mod_python 3.x, and you should use Apache's `prefork MPM`_, as opposed to the `worker MPM`_. -You may also be interested in `How to use Django with FastCGI`_. +You may also be interested in :doc:`How to use Django with FastCGI `. .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _mod_perl: http://perl.apache.org/ .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html -.. _How to use Django with FastCGI: http://www.djangoproject.com/documentation/fastcgi/ Basic configuration =================== diff --git a/docs/outputting_csv.txt b/docs/outputting_csv.txt index 1970261891b4..d72a27623582 100644 --- a/docs/outputting_csv.txt +++ b/docs/outputting_csv.txt @@ -20,11 +20,10 @@ and Django's ``HttpResponse`` objects are file-like objects. .. admonition:: Note For more information on ``HttpResponse`` objects, see - `Request and response objects`_. + :doc:`Request and response objects `. For more information on the CSV library, see the `CSV library docs`_. - .. _Request and response objects: http://www.djangoproject.com/documentation/request_response/ .. _CSV library docs: http://www.python.org/doc/current/lib/module-csv.html Here's an example:: @@ -70,7 +69,7 @@ mention: Using the template system ========================= -Alternatively, you can use the `Django template system`_ to generate CSV. This +Alternatively, you can use the :doc:`Django template system ` to generate CSV. This is lower-level than using the convenient CSV, but the solution is presented here for completeness. @@ -111,9 +110,6 @@ Then, create the template ``my_template_name.txt``, with this template code:: {% endfor %} This template is quite basic. It just iterates over the given data and displays -a line of CSV for each row. It uses the `addslashes template filter`_ to ensure +a line of CSV for each row. It uses the :doc:`addslashes template filter ` to ensure there aren't any problems with quotes. If you can be certain your data doesn't have single or double quotes in it, you can remove the ``addslashes`` filters. - -.. _Django template system: http://www.djangoproject.com/documentation/templates/ -.. _addslashes template filter: http://www.djangoproject.com/documentation/templates/#addslashes diff --git a/docs/outputting_pdf.txt b/docs/outputting_pdf.txt index edd34aca2432..08cf9e2c9f4a 100644 --- a/docs/outputting_pdf.txt +++ b/docs/outputting_pdf.txt @@ -41,9 +41,7 @@ objects. .. admonition:: Note For more information on ``HttpResponse`` objects, see - `Request and response objects`_. - - .. _Request and response objects: http://www.djangoproject.com/documentation/request_response/ + :doc:`Request and response objects `. Here's a "Hello World" example:: diff --git a/docs/overview.txt b/docs/overview.txt index 5a399582e82c..72bd099dd703 100644 --- a/docs/overview.txt +++ b/docs/overview.txt @@ -8,11 +8,9 @@ overview of how to write a database-driven Web app with Django. The goal of this document is to give you enough technical specifics to understand how Django works, but this isn't intended to be a tutorial or -reference. Please see our more-detailed Django documentation_ when you're ready +reference. Please see our more-detailed Django :doc:`documentation ` when you're ready to start a project. -.. _documentation: http://www.djangoproject.com/documentation/ - Design your model ================= @@ -293,9 +291,8 @@ features: * More sexy automatically-generated admin features -- this overview barely scratched the surface. -The next obvious steps are for you to `download Django`_, read `the tutorial`_ +The next obvious steps are for you to `download Django`_, read :doc:`the tutorial ` and join `the community`_. Thanks for your interest! .. _download Django: http://www.djangoproject.com/download/ -.. _the tutorial: http://www.djangoproject.com/documentation/tutorial1/ .. _the community: http://www.djangoproject.com/community/ diff --git a/docs/redirects.txt b/docs/redirects.txt index e0bcb2f1fa7c..57e12a2a7ea0 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -10,14 +10,11 @@ Installation To install the redirects app, follow these steps: - 1. Add ``'django.contrib.redirects'`` to your INSTALLED_APPS_ setting. + 1. Add ``'django.contrib.redirects'`` to your :doc:`INSTALLED_APPS ` setting. 2. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` - to your MIDDLEWARE_CLASSES_ setting. + to your :doc:`MIDDLEWARE_CLASSES ` setting. 3. Run the command ``manage.py syncdb``. -.. _INSTALLED_APPS: http://www.djangoproject.com/documentation/settings/#installed-apps -.. _MIDDLEWARE_CLASSES: http://www.djangoproject.com/documentation/settings/#middleware-classes - How it works ============ @@ -27,7 +24,7 @@ is a simple lookup table with ``site_id``, ``old_path`` and ``new_path`` fields. The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django application raises a 404 error, this middleware checks the redirects database for the requested URL as a last resort. Specifically, it checks for a redirect -with the given ``old_path`` with a site ID that corresponds to the SITE_ID_ +with the given ``old_path`` with a site ID that corresponds to the :doc:`SITE_ID ` setting. * If it finds a match, and ``new_path`` is not empty, it redirects to @@ -44,10 +41,7 @@ Note that the order of ``MIDDLEWARE_CLASSES`` matters. Generally, you can put ``RedirectFallbackMiddleware`` at the end of the list, because it's a last resort. -For more on middleware, read the `middleware docs`_. - -.. _SITE_ID: http://www.djangoproject.com/documentation/settings/#site-id -.. _middleware docs: http://www.djangoproject.com/documentation/middleware/ +For more on middleware, read the :doc:`middleware docs `. How to add, change and delete redirects ======================================= @@ -62,10 +56,8 @@ other object in the system. Via the Python API ------------------ -Redirects are represented by a standard `Django model`_, which lives in +Redirects are represented by a standard :doc:`Django model `, which lives in `django/contrib/redirects/models/redirects.py`_. You can access redirect -objects via the `Django database API`_. +objects via the :doc:`Django database API `. -.. _Django model: http://www.djangoproject.com/documentation/model_api/ .. _django/contrib/redirects/models/redirects.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models/redirects.py -.. _Django database API: http://www.djangoproject.com/documentation/db_api/ diff --git a/docs/release_notes_0.95.txt b/docs/release_notes_0.95.txt index bf6a54b47c8a..ff11a69520b1 100644 --- a/docs/release_notes_0.95.txt +++ b/docs/release_notes_0.95.txt @@ -106,9 +106,9 @@ initial release of Django 0.95; these include: * A patch which disables debugging mode in the flup FastCGI package Django uses to launch its FastCGI server, which prevents tracebacks from bubbling up during production use. - - * A security fix to the i18n framework which could allow an - attacker to send extremely large strings in the Accept-Language + + * A security fix to the i18n framework which could allow an + attacker to send extremely large strings in the Accept-Language header and cause a denial of service by filling available memory. Because these problems weren't discovered and fixed until after the @@ -119,7 +119,7 @@ Problem reports and getting help ================================ Need help resolving a problem with Django? The documentation in the -distribution is also available online_ at the `Django website`_. The FAQ_ +distribution is also available :doc:`online ` at the `Django website`_. The :doc:`FAQ ` document is especially recommended, as it contains a number of issues that come up time and again. @@ -134,9 +134,7 @@ there's a #django channel or irc.freenode.net that is regularly populated by Django users and developers from around the world. Friendly people are usually available at any hour of the day -- to help, or just to chat. -.. _online: http://www.djangoproject.com/documentation/ .. _Django website: http://www.djangoproject.com/ -.. _FAQ: http://www.djangoproject.com/documentation/faq/ .. _django-users: http://groups.google.com/group/django-users Thanks for using Django! diff --git a/docs/request_response.txt b/docs/request_response.txt index 7480a6d3bb33..a7a59062c144 100644 --- a/docs/request_response.txt +++ b/docs/request_response.txt @@ -115,16 +115,12 @@ All attributes except ``session`` should be considered read-only. ``user`` is only available if your Django installation has the ``AuthenticationMiddleware`` activated. For more, see - `Authentication in Web requests`_. - - .. _Authentication in Web requests: http://www.djangoproject.com/documentation/authentication/#authentication-in-web-requests + :doc:`Authentication in Web requests `. ``session`` A readable-and-writable, dictionary-like object that represents the current session. This is only available if your Django installation has session - support activated. See the `session documentation`_ for full details. - - .. _`session documentation`: http://www.djangoproject.com/documentation/sessions/ + support activated. See the :doc:`session documentation ` for full details. ``raw_post_data`` The raw HTTP POST data. This is only useful for advanced processing. Use @@ -149,7 +145,7 @@ Methods Returns the ``path``, plus an appended query string, if applicable. Example: ``"/music/bands/the_beatles/?print=true"`` - + ``is_secure()`` Returns ``True`` if the request is secure; that is, if it was made with HTTPS. diff --git a/docs/serialization.txt b/docs/serialization.txt index 25199e7a50b7..3e8fd2043ce7 100644 --- a/docs/serialization.txt +++ b/docs/serialization.txt @@ -3,12 +3,12 @@ Serializing Django objects ========================== .. note:: - + This API is currently under heavy development and may change -- perhaps drastically -- in the future. - + You have been warned. - + Django's serialization framework provides a mechanism for "translating" Django objects into other formats. Usually these other formats will be text-based and used for sending Django objects over a wire, but it's possible for a @@ -21,28 +21,24 @@ At the highest level, serializing data is a very simple operation:: from django.core import serializers data = serializers.serialize("xml", SomeModel.objects.all()) - + The arguments to the ``serialize`` function are the format to serialize the -data to (see `Serialization formats`_) and a QuerySet_ to serialize. +data to (see `Serialization formats`_) and a :doc:`QuerySet ` to serialize. (Actually, the second argument can be any iterator that yields Django objects, but it'll almost always be a QuerySet). -.. _QuerySet: ../db_api/#retrieving-objects - You can also use a serializer object directly:: xml_serializer = serializers.get_serializer("xml") xml_serializer.serialize(queryset) data = xml_serializer.getvalue() - + This is useful if you want to serialize data directly to a file-like object -(which includes a HTTPResponse_):: +(which includes a :doc:`HTTPResponse `):: out = open("file.xml", "w") xml_serializer.serialize(SomeModel.objects.all(), stream=out) -.. _HTTPResponse: ../request_response/#httpresponse-objects - Deserializing data ------------------ @@ -50,7 +46,7 @@ Deserializing data is also a fairly simple operation:: for obj in serializers.deserialize("xml", data): do_something_with(obj) - + As you can see, the ``deserialize`` function takes the same format argument as ``serialize``, a string or stream of data, and returns an iterator. @@ -69,7 +65,7 @@ something like:: for deserialized_object in serializers.deserialize("xml", data): if object_should_be_saved(deserialized_object): obj.save() - + In other words, the usual use is to examine the deserialized objects to make sure that they are "appropriate" for saving before doing so. Of course, if you trust your data source you could just save the object and move on. @@ -89,7 +85,7 @@ Django "ships" with a few included serializers: bundled with Django). ``python`` Translates to and from "simple" Python objects (lists, dicts, - strings, etc.). Not really all that useful on its own, but + strings, etc.). Not really all that useful on its own, but used as a base for other serializers. ========== ============================================================== diff --git a/docs/sessions.txt b/docs/sessions.txt index c473d0a3db62..eb5f280fc5be 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -10,7 +10,7 @@ Cookies contain a session ID -- not the data itself. Enabling sessions ================= -Sessions are implemented via a piece of middleware_ and a Django model. +Sessions are implemented via a piece of :doc:`middleware ` and a Django model. To enable session functionality, do these two things: @@ -27,8 +27,6 @@ If you don't want to use sessions, you might as well remove the ``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'`` from your ``INSTALLED_APPS``. It'll save you a small bit of overhead. -.. _middleware: http://www.djangoproject.com/documentation/middleware/ - Using sessions in views ======================= @@ -220,7 +218,7 @@ a browser. Settings ======== -A few `Django settings`_ give you control over session behavior: +A few :doc:`Django settings ` give you control over session behavior: SESSION_COOKIE_AGE ------------------ @@ -262,8 +260,6 @@ Whether to save the session data on every request. If this is ``False`` (default), then the session data will only be saved if it has been modified -- that is, if any of its dictionary values have been assigned or deleted. -.. _Django settings: http://www.djangoproject.com/documentation/settings/ - Technical details ================= diff --git a/docs/settings.txt b/docs/settings.txt index 099196e56e1e..f6223c226dcf 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -42,7 +42,7 @@ Python `import search path`_. The django-admin.py utility --------------------------- -When using `django-admin.py`_, you can either set the environment variable +When using :doc:`django-admin.py `, you can either set the environment variable once, or explicitly pass in the settings module each time you run the utility. Example (Unix Bash shell):: @@ -59,8 +59,6 @@ Use the ``--settings`` command-line argument to specify the settings manually:: django-admin.py runserver --settings=mysite.settings -.. _django-admin.py: http://www.djangoproject.com/documentation/django_admin/ - On the server (mod_python) -------------------------- @@ -73,9 +71,7 @@ settings file to use. Do that with ``SetEnv``:: SetEnv DJANGO_SETTINGS_MODULE mysite.settings -Read the `Django mod_python documentation`_ for more information. - -.. _Django mod_python documentation: http://www.djangoproject.com/documentation/modpython/ +Read the :doc:`Django mod_python documentation ` for more information. Default settings ================ @@ -100,9 +96,7 @@ There's an easy way to view which of your settings deviate from the default settings. The command ``python manage.py diffsettings`` displays differences between the current settings file and Django's default settings. -For more, see the `diffsettings documentation`_. - -.. _diffsettings documentation: http://www.djangoproject.com/documentation/django_admin/#diffsettings +For more, see the :doc:`diffsettings documentation `. Using settings in Python code ============================= @@ -216,7 +210,7 @@ APPEND_SLASH Default: ``True`` Whether to append trailing slashes to URLs. This is only used if -``CommonMiddleware`` is installed (see the `middleware docs`_). See also +``CommonMiddleware`` is installed (see the :doc:`middleware docs `). See also ``PREPEND_WWW``. CACHE_BACKEND @@ -224,14 +218,14 @@ CACHE_BACKEND Default: ``'simple://'`` -The cache backend to use. See the `cache docs`_. +The cache backend to use. See the :doc:`cache docs `. CACHE_MIDDLEWARE_KEY_PREFIX Default: ``''`` (Empty string) The cache key prefix that the cache middleware should use. See the -`cache docs`_. +:doc:`cache docs `. DATABASE_ENGINE --------------- @@ -294,12 +288,10 @@ Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``) The default formatting to use for date fields on Django admin change-list pages -- and, possibly, by other parts of the system. See -`allowed date format strings`_. +:doc:`allowed date format strings `. See also DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. -.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now - DATETIME_FORMAT --------------- @@ -307,12 +299,10 @@ Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``) The default formatting to use for datetime fields on Django admin change-list pages -- and, possibly, by other parts of the system. See -`allowed date format strings`_. +:doc:`allowed date format strings `. See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. -.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now - DEBUG ----- @@ -354,7 +344,7 @@ Default: ``()`` (Empty tuple) List of compiled regular expression objects representing User-Agent strings that are not allowed to visit any page, systemwide. Use this for bad robots/crawlers. This is only used if ``CommonMiddleware`` is installed (see -the `middleware docs`_). +the :doc:`middleware docs `). EMAIL_HOST ---------- @@ -432,9 +422,7 @@ Default: ``()`` (Empty tuple) A tuple of strings designating all applications that are enabled in this Django installation. Each string should be a full Python path to a Python package that -contains a Django application, as created by `django-admin.py startapp`_. - -.. _django-admin.py startapp: http://www.djangoproject.com/documentation/django_admin/#startapp-appname +contains a Django application, as created by :doc:`django-admin.py startapp `. INTERNAL_IPS ------------ @@ -445,7 +433,7 @@ A tuple of IP addresses, as strings, that: * See debug comments, when ``DEBUG`` is ``True`` * Receive X headers if the ``XViewMiddleware`` is installed (see the - `middleware docs`_) + :doc:`middleware docs `) JING_PATH --------- @@ -463,9 +451,7 @@ Default: ``'en-us'`` A string representing the language code for this installation. This should be in standard language format. For example, U.S. English is ``"en-us"``. See the -`internationalization docs`_. - -.. _internationalization docs: http://www.djangoproject.com/documentation/i18n/ +:doc:`internationalization docs `. LANGUAGES --------- @@ -496,7 +482,7 @@ Default: A tuple of all available languages. Currently, this is:: A tuple of two-tuples in the format (language code, language name). This specifies which languages are available for language selection. See the -`internationalization docs`_ for details. +:doc:`internationalization docs ` for details. Generally, the default value should suffice. Only set this setting if you want to restrict language selection to a subset of the Django-provided languages. @@ -557,7 +543,7 @@ Default:: "django.middleware.common.CommonMiddleware", "django.middleware.doc.XViewMiddleware") -A tuple of middleware classes to use. See the `middleware docs`_. +A tuple of middleware classes to use. See the :doc:`middleware docs `. MONTH_DAY_FORMAT ---------------- @@ -573,7 +559,7 @@ drilldown, the header for a given day displays the day and month. Different locales have different formats. For example, U.S. English would say "January 1," whereas Spanish might say "1 Enero." -See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT, +See :doc:`allowed date format strings `. See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT and YEAR_MONTH_FORMAT. PREPEND_WWW @@ -582,7 +568,7 @@ PREPEND_WWW Default: ``False`` Whether to prepend the "www." subdomain to URLs that don't have it. This is -only used if ``CommonMiddleware`` is installed (see the `middleware docs`_). +only used if ``CommonMiddleware`` is installed (see the :doc:`middleware docs `). See also ``APPEND_SLASH``. ROOT_URLCONF @@ -591,9 +577,7 @@ ROOT_URLCONF Default: Not defined A string representing the full Python import path to your root URLconf. For example: -``"mydjangoapps.urls"``. See `How Django processes a request`_. - -.. _How Django processes a request: http://www.djangoproject.com/documentation/url_dispatch/#how-django-processes-a-request +``"mydjangoapps.urls"``. See :doc:`How Django processes a request `. SECRET_KEY ---------- @@ -612,7 +596,7 @@ Default: ``False`` Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a Django-powered page that is 404ed with a non-empty referer (i.e., a broken link). This is only used if ``CommonMiddleware`` is installed (see the -`middleware docs`_). See also ``IGNORABLE_404_STARTS`` and +:doc:`middleware docs `). See also ``IGNORABLE_404_STARTS`` and ``IGNORABLE_404_ENDS``. SERVER_EMAIL @@ -628,7 +612,7 @@ SESSION_COOKIE_AGE Default: ``1209600`` (2 weeks, in seconds) -The age of session cookies, in seconds. See the `session docs`_. +The age of session cookies, in seconds. See the :doc:`session docs `. SESSION_COOKIE_DOMAIN --------------------- @@ -637,7 +621,7 @@ Default: ``None`` The domain to use for session cookies. Set this to a string such as ``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard -domain cookie. See the `session docs`_. +domain cookie. See the :doc:`session docs `. SESSION_COOKIE_NAME ------------------- @@ -645,7 +629,7 @@ SESSION_COOKIE_NAME Default: ``'sessionid'`` The name of the cookie to use for sessions. This can be whatever you want. -See the `session docs`_. +See the :doc:`session docs `. SESSION_EXPIRE_AT_BROWSER_CLOSE ------------------------------- @@ -653,14 +637,14 @@ SESSION_EXPIRE_AT_BROWSER_CLOSE Default: ``False`` Whether to expire the session when the user closes his or her browser. -See the `session docs`_. +See the :doc:`session docs `. SESSION_SAVE_EVERY_REQUEST -------------------------- Default: ``False`` -Whether to save the session data on every request. See the `session docs`_. +Whether to save the session data on every request. See the :doc:`session docs `. SITE_ID ------- @@ -671,9 +655,7 @@ The ID, as an integer, of the current site in the ``django_site`` database table. This is used so that application data can hook into specific site(s) and a single database can manage content for multiple sites. -See the `site framework docs`_. - -.. _site framework docs: http://www.djangoproject.com/documentation/sites/ +See the :doc:`site framework docs `. TEMPLATE_CONTEXT_PROCESSORS --------------------------- @@ -711,7 +693,7 @@ Default: ``()`` (Empty tuple) List of locations of the template source files, in search order. Note that these paths should use Unix-style forward slashes, even on Windows. -See the `template documentation`_. +See the :doc:`template documentation `. TEMPLATE_LOADERS ---------------- @@ -719,7 +701,7 @@ TEMPLATE_LOADERS Default: ``('django.template.loaders.filesystem.load_template_source',)`` A tuple of callables (as strings) that know how to import templates from -various sources. See the `template documentation`_. +various sources. See the :doc:`template documentation `. TEMPLATE_STRING_IF_INVALID -------------------------- @@ -727,9 +709,7 @@ TEMPLATE_STRING_IF_INVALID Default: ``''`` (Empty string) Output, as a string, that the template system should use for invalid (e.g. -misspelled) variables. See `How invalid variables are handled`_. - -.. _How invalid variables are handled: http://www.djangoproject.com/documentation/templates_python/#how-invalid-variables-are-handled +misspelled) variables. See :doc:`How invalid variables are handled `. TIME_FORMAT ----------- @@ -738,13 +718,11 @@ Default: ``'P'`` (e.g. ``4 p.m.``) The default formatting to use for time fields on Django admin change-list pages -- and, possibly, by other parts of the system. See -`allowed date format strings`_. +:doc:`allowed date format strings `. See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT. -.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now - TIME_ZONE --------- @@ -774,7 +752,7 @@ Default: ``False`` A boolean that specifies whether to output the "Etag" header. This saves bandwidth but slows down performance. This is only used if ``CommonMiddleware`` -is installed (see the `middleware docs`_). +is installed (see the :doc:`middleware docs `). USE_I18N -------- @@ -800,14 +778,10 @@ drilldown, the header for a given month displays the month and the year. Different locales have different formats. For example, U.S. English would say "January 2006," whereas another locale might say "2006/January." -See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT, +See :doc:`allowed date format strings `. See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT and MONTH_DAY_FORMAT. -.. _cache docs: http://www.djangoproject.com/documentation/cache/ -.. _middleware docs: http://www.djangoproject.com/documentation/middleware/ -.. _session docs: http://www.djangoproject.com/documentation/sessions/ .. _See available choices: http://www.postgresql.org/docs/current/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE -.. _template documentation: http://www.djangoproject.com/documentation/templates_python/ Creating your own settings ========================== diff --git a/docs/sites.txt b/docs/sites.txt index cca9f14f3160..7ff8be779131 100644 --- a/docs/sites.txt +++ b/docs/sites.txt @@ -217,7 +217,7 @@ The ``CurrentSiteManager`` ========================== If ``Site``\s play a key role in your application, consider using the helpful -``CurrentSiteManager`` in your model(s). It's a model manager_ that +``CurrentSiteManager`` in your model(s). It's a model :doc:`manager ` that automatically filters its queries to include only objects associated with the current ``Site``. @@ -266,8 +266,6 @@ this:: If you attempt to use ``CurrentSiteManager`` and pass a field name that doesn't exist, Django will raise a ``ValueError``. -.. _manager: http://www.djangoproject.com/documentation/model_api/#managers - How Django uses the sites framework =================================== @@ -279,7 +277,7 @@ to its ID in your ``SITE_ID`` setting. Here's how Django uses the sites framework: - * In the `redirects framework`_, each redirect object is associated with a + * In the :doc:`redirects framework `, each redirect object is associated with a particular site. When Django searches for a redirect, it takes into account the current ``SITE_ID``. @@ -288,24 +286,19 @@ Here's how Django uses the sites framework: ``SITE_ID``, and when comments are listed via the appropriate template tag, only the comments for the current site are displayed. - * In the `flatpages framework`_, each flatpage is associated with a + * In the :doc:`flatpages framework `, each flatpage is associated with a particular site. When a flatpage is created, you specify its ``site``, and the ``FlatpageFallbackMiddleware`` checks the current ``SITE_ID`` in retrieving flatpages to display. - * In the `syndication framework`_, the templates for ``title`` and + * In the :doc:`syndication framework `, the templates for ``title`` and ``description`` automatically have access to a variable ``{{{ site }}}``, which is the ``Site`` object representing the current site. Also, the hook for providing item URLs will use the ``domain`` from the current ``Site`` object if you don't specify a fully-qualified domain. - * In the `authentication framework`_, the ``django.contrib.auth.views.login`` + * In the :doc:`authentication framework `, the ``django.contrib.auth.views.login`` view passes the current ``Site`` name to the template as ``{{{ site_name }}}``. * The shortcut view (``django.views.defaults.shortcut``) uses the domain of the current ``Site`` object when calculating an object's URL. - -.. _redirects framework: http://www.djangoproject.com/documentation/redirects/ -.. _flatpages framework: http://www.djangoproject.com/documentation/flatpages/ -.. _syndication framework: http://www.djangoproject.com/documentation/syndication/ -.. _authentication framework: http://www.djangoproject.com/documentation/authentication/ diff --git a/docs/static_files.txt b/docs/static_files.txt index d8d90e52d556..66c4e1b7bd17 100644 --- a/docs/static_files.txt +++ b/docs/static_files.txt @@ -22,14 +22,12 @@ Using this method is **inefficient** and **insecure**. Do not use this in a production setting. Use this only for development. For information on serving static files in an Apache production environment, -see the `Django mod_python documentation`_. - -.. _Django mod_python documentation: http://www.djangoproject.com/documentation/modpython/#serving-media-files +see the :doc:`Django mod_python documentation `. How to do it ============ -Just put this in your URLconf_:: +Just put this in your :doc:`URLconf `:: (r'^site_media/(.*)$', 'django.views.static.serve', {'document_root': '/path/to/media'}), @@ -49,8 +47,6 @@ Examples: * The file ``/path/bar.jpg`` will not be accessible, because it doesn't fall under the document root. -.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/ - Directory listings ================== @@ -121,5 +117,3 @@ associated with the ``django.views.static.serve`` view. If not Of course, the catch here is that you'll have to remember to set ``DEBUG=False`` in your production settings file. But you should be doing that anyway. - -.. _DEBUG setting: http://www.djangoproject.com/documentation/settings/#debug diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt index b00af200a09e..d4cf2799cbd3 100644 --- a/docs/syndication_feeds.txt +++ b/docs/syndication_feeds.txt @@ -24,15 +24,13 @@ The high-level feed-generating framework is a view that's hooked to ``/feeds/`` by default. Django uses the remainder of the URL (everything after ``/feeds/``) to determine which feed to output. -To create a feed, just write a ``Feed`` class and point to it in your URLconf_. - -.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/ +To create a feed, just write a ``Feed`` class and point to it in your :doc:`URLconf `. Initialization -------------- To activate syndication feeds on your Django site, add this line to your -URLconf_:: +:doc:`URLconf `:: (r'^feeds/(?P.*)/$', 'django.contrib.syndication.views.feed', {'feed_dict': feeds}), @@ -72,9 +70,6 @@ The above example registers two feeds: Once that's set up, you just need to define the ``Feed`` classes themselves. -.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/ -.. _settings file: http://www.djangoproject.com/documentation/settings/ - Feed classes ------------ @@ -111,7 +106,7 @@ Note: * ``items()`` is, simply, a method that returns a list of objects that should be included in the feed as ```` elements. Although this example returns ``NewsItem`` objects using Django's - `object-relational mapper`_, ``items()`` doesn't have to return model + :doc:`object-relational mapper `, ``items()`` doesn't have to return model instances. Although you get a few bits of functionality "for free" by using Django models, ``items()`` can return any type of object you want. @@ -120,7 +115,7 @@ One thing's left to do. In an RSS feed, each ```` has a ````, put into those elements. * To specify the contents of ``<title>`` and ``<description>``, create - `Django templates`_ called ``feeds/sitenews_title.html`` and + :doc:`Django templates <templates>` called ``feeds/sitenews_title.html`` and ``feeds/sitenews_description.html``, where ``sitenews`` is the ``slug`` specified in the URLconf for the given feed. Note the ``.html`` extension is required. The RSS system renders that template for each item, passing @@ -146,8 +141,6 @@ put into those elements. URL as a normal Python string. .. _chicagocrime.org: http://www.chicagocrime.org/ -.. _object-relational mapper: http://www.djangoproject.com/documentation/db_api/ -.. _Django templates: http://www.djangoproject.com/documentation/templates/ A complex example ----------------- @@ -265,9 +258,7 @@ Language Feeds created by the syndication framework automatically include the appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). This -comes directly from your `LANGUAGE_CODE setting`_. - -.. _LANGUAGE_CODE setting: http://www.djangoproject.com/documentation/settings/#language-code +comes directly from your :doc:`LANGUAGE_CODE setting <settings>`. URLs ---- @@ -276,14 +267,12 @@ The ``link`` method/attribute can return either an absolute URL (e.g. ``"/blog/"``) or a URL with the fully-qualified domain and protocol (e.g. ``"http://www.example.com/blog/"``). If ``link`` doesn't return the domain, the syndication framework will insert the domain of the current site, according -to your `SITE_ID setting`_. +to your :doc:`SITE_ID setting <settings>`. Atom feeds require a ``<link rel="self">`` that defines the feed's current location. The syndication framework populates this automatically, using the domain of the current site according to the SITE_ID setting. -.. _SITE_ID setting: http://www.djangoproject.com/documentation/settings/#site-id - Publishing Atom and RSS feeds in tandem --------------------------------------- diff --git a/docs/templates.txt b/docs/templates.txt index 49d30018fe9d..2892a39f5c96 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -363,7 +363,7 @@ extends Signal that this template extends a parent template. -This tag can be used in two ways: +This tag can be used in two ways: * ``{% extends "base.html" %}`` (with quotes) uses the literal value ``"base.html"`` as the name of the parent template to extend. @@ -753,12 +753,10 @@ file are evaluated as template code, within the current context:: {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %} Note that if you use ``{% ssi %}``, you'll need to define -`ALLOWED_INCLUDE_ROOTS`_ in your Django settings, as a security measure. +:doc:`ALLOWED_INCLUDE_ROOTS <settings>` in your Django settings, as a security measure. See also: ``{% include %}``. -.. _ALLOWED_INCLUDE_ROOTS: http://www.djangoproject.com/documentation/settings/#allowed-include-roots - templatetag ~~~~~~~~~~~ @@ -961,13 +959,13 @@ any string. pluralize ~~~~~~~~~ -Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``. +Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``. Example:: You have {{ num_messages }} message{{ num_messages|pluralize }}. -For words that require a suffix other than ``'s'``, you can provide an alternate +For words that require a suffix other than ``'s'``, you can provide an alternate suffix as a parameter to the filter. Example:: @@ -1159,9 +1157,7 @@ django.contrib.humanize ----------------------- A set of Django template filters useful for adding a "human touch" to data. See -the `humanize documentation`_. - -.. _humanize documentation: http://www.djangoproject.com/documentation/add_ons/#humanize +the :doc:`humanize documentation <add_ons>`. django.contrib.markup --------------------- diff --git a/docs/templates_python.txt b/docs/templates_python.txt index 95ccfb3eab3c..482179656700 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -5,14 +5,12 @@ The Django template language: For Python programmers This document explains the Django template system from a technical perspective -- how it works and how to extend it. If you're just looking for reference on the language syntax, see -`The Django template language: For template authors`_. +:doc:`The Django template language: For template authors <templates>`. If you're looking to use the Django template system as part of another application -- i.e., without the rest of the framework -- make sure to read the `configuration`_ section later in this document. -.. _`The Django template language: For template authors`: http://www.djangoproject.com/documentation/templates/ - Basics ====== @@ -250,14 +248,14 @@ Subclassing Context: RequestContext Django comes with a special ``Context`` class, ``django.template.RequestContext``, that acts slightly differently than the normal ``django.template.Context``. The first difference is that takes -an `HttpRequest object`_ as its first argument. For example:: +an :doc:`HttpRequest object <request_response>` as its first argument. For example:: c = RequestContext(request, { 'foo': 'bar', } The second difference is that it automatically populates the context with a few -variables, according to your `TEMPLATE_CONTEXT_PROCESSORS setting`_. +variables, according to your :doc:`TEMPLATE_CONTEXT_PROCESSORS setting <settings>`. The ``TEMPLATE_CONTEXT_PROCESSORS`` setting is a tuple of callables that take a request object as their argument and return a dictionary of items to be merged @@ -287,9 +285,6 @@ optional, third positional argument, ``processors``. In this example, the Here's what each of the default processors does: -.. _HttpRequest object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects -.. _TEMPLATE_CONTEXT_PROCESSORS setting: http://www.djangoproject.com/documentation/settings/#template-context-processors - django.core.context_processors.auth ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -298,15 +293,12 @@ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every * ``user`` -- An ``auth.User`` instance representing the currently logged-in user (or an ``AnonymousUser`` instance, if the client isn't - logged in). See the `user authentication docs`. + logged in). See the :doc:`user authentication docs <authentication>`. * ``messages`` -- A list of ``auth.Message`` objects for the currently logged-in user. * ``perms`` -- An instance of ``django.core.context_processors.PermWrapper``, representing the permissions that the currently logged-in user has. See - the `permissions docs`_. - -.. _user authentication docs: http://www.djangoproject.com/documentation/authentication/#users -.. _permissions docs: http://www.djangoproject.com/documentation/authentication/#permissions + the :doc:`permissions docs <authentication>`. django.core.context_processors.debug ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -328,22 +320,18 @@ django.core.context_processors.i18n If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every ``RequestContext`` will contain these two variables: - * ``LANGUAGES`` -- The value of the `LANGUAGES setting`_. + * ``LANGUAGES`` -- The value of the :doc:`LANGUAGES setting <settings>`. * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise, - the value of the `LANGUAGE_CODE setting`_. + the value of the :doc:`LANGUAGE_CODE setting <settings>`. -See the `internationalization docs`_ for more. - -.. _LANGUAGES setting: http://www.djangoproject.com/documentation/settings/#languages -.. _LANGUAGE_CODE setting: http://www.djangoproject.com/documentation/settings/#language-code -.. _internationalization docs: http://www.djangoproject.com/documentation/i18n/ +See the :doc:`internationalization docs <i18n>` for more. django.core.context_processors.request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every ``RequestContext`` will contain a variable ``request``, which is the current -`HttpRequest object`_. Note that this processor is not enabled by default; +:doc:`HttpRequest object <request_response>`. Note that this processor is not enabled by default; you'll have to activate it. Loading templates @@ -790,7 +778,7 @@ These sorts of tags are called `inclusion tags`. Writing inclusion tags is probably best demonstrated by example. Let's write a tag that outputs a list of choices for a given ``Poll`` object, such as was -created in the tutorials_. We'll use the tag like this:: +created in the :doc:`tutorials <tutorial01>`. We'll use the tag like this:: {% show_results poll %} @@ -878,8 +866,6 @@ The ``takes_context`` parameter defaults to ``False``. When it's set to *True*, the tag is passed the context object, as in this example. That's the only difference between this case and the previous ``inclusion_tag`` example. -.. _tutorials: http://www.djangoproject.com/documentation/tutorial1/#creating-models - Setting a variable in the context ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1039,15 +1025,12 @@ template system in line with the rest of your application rather than dealing with settings files and pointing to them via environment variables. To solve this problem, you need to use the manual configuration option -described in the `settings file`_ documentation. Simply import the appropriate +described in the :doc:`settings file <settings>` documentation. Simply import the appropriate pieces of the templating system and then, *before* you call any of the templating functions, call ``django.conf.settings.configure()`` with any settings you wish to specify. You might want to consider setting at least ``TEMPLATE_DIRS`` (if you are going to use template loaders), ``DEFAULT_CHARSET`` (although the default of ``utf-8`` is probably fine) and ``TEMPLATE_DEBUG``. All available settings are described in the -`settings documentation`_, and any setting starting with *TEMPLATE_* +:doc:`settings documentation <settings>`, and any setting starting with *TEMPLATE_* is of obvious interest. - -.. _settings file: http://www.djangoproject.com/documentation/settings/#using-settings-without-the-django-settings-module-environment-variable -.. _settings documentation: http://www.djangoproject.com/documentation/settings/ diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt index 1113b603da9a..75b6d8d8ff27 100644 --- a/docs/tutorial01.txt +++ b/docs/tutorial01.txt @@ -12,13 +12,11 @@ It'll consist of two parts: * A public site that lets people view polls and vote in them. * An admin site that lets you add, change and delete poll. -We'll assume you have `Django installed`_ already. You can tell Django is +We'll assume you have :doc:`Django installed <install>` already. You can tell Django is installed by running the Python interactive interpreter and typing ``import django``. If that command runs successfully, with no errors, Django is installed. -.. _`Django installed`: http://www.djangoproject.com/documentation/install/ - Creating a project ================== @@ -106,9 +104,7 @@ It worked! python manage.py runserver 8080 - Full docs for the development server are at `django-admin documentation`_. - -.. _django-admin documentation: http://www.djangoproject.com/documentation/django_admin/ + Full docs for the development server are at :doc:`django-admin documentation <django-admin>`. Database setup -------------- @@ -375,11 +371,9 @@ all the tables, initial data and indexes for any apps you have added to your project since the last time you ran syncdb. ``syncdb`` can be called as often as you like, and it will only ever create the tables that don't exist. -Read the `django-admin.py documentation`_ for full information on what the +Read the :doc:`django-admin.py documentation <django-admin>` for full information on what the ``manage.py`` utility can do. -.. _django-admin.py documentation: http://www.djangoproject.com/documentation/django_admin/ - Playing with the API ==================== @@ -410,7 +404,9 @@ things: ``import mysite`` works) and set the ``DJANGO_SETTINGS_MODULE`` environment variable to ``mysite.settings``. - For more information on all of this, see the `django-admin.py documentation`_. + For more information on all of this, see the :doc:`django-admin.py documentation <django-admin>`. + hlsearch + Once you're in the shell, explore the database API:: @@ -550,10 +546,7 @@ Let's jump back into the Python interactive shell by running >>> c = p.choice_set.filter(choice__startswith='Just hacking') >>> c.delete() -For full details on the database API, see our `Database API reference`_. +For full details on the database API, see our :doc:`Database API reference <db-api>`. -When you're comfortable with the API, read `part 2 of this tutorial`_ to get +When you're comfortable with the API, read :doc:`part 2 of this tutorial <tutorial02>` to get Django's automatic admin working. - -.. _Database API reference: http://www.djangoproject.com/documentation/db_api/ -.. _part 2 of this tutorial: http://www.djangoproject.com/documentation/tutorial2/ diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt index bc1717e67c20..fd415c033188 100644 --- a/docs/tutorial02.txt +++ b/docs/tutorial02.txt @@ -2,11 +2,9 @@ Writing your first Django app, part 2 ===================================== -This tutorial begins where `Tutorial 1`_ left off. We're continuing the Web-poll +This tutorial begins where :doc:`Tutorial 1 <tutorial01>` left off. We're continuing the Web-poll application and will focus on Django's automatically-generated admin site. -.. _Tutorial 1: http://www.djangoproject.com/documentation/tutorial1/ - .. admonition:: Philosophy Generating admin sites for your staff or clients to add, change and delete @@ -64,8 +62,6 @@ tutorial, remember?) You should see the Django admin index page: By default, you should see two types of editable content: groups and users. These are core features Django ships with by default. -.. _"I can't log in" questions: http://www.djangoproject.com/documentation/faq/#the-admin-site - Make the poll app modifiable in the admin ========================================= @@ -399,11 +395,9 @@ changes. Astute readers will ask: But if ``TEMPLATE_DIRS`` was empty by default, how was Django finding the default admin templates? The answer is that, by default, Django automatically looks for a ``templates/`` subdirectory within each app -package, for use as a fallback. See the `loader types documentation`_ for full +package, for use as a fallback. See the :doc:`loader types documentation <templates_python>` for full information. -.. _loader types documentation: http://www.djangoproject.com/documentation/templates_python/#loader-types - Customize the admin index page ============================== @@ -428,10 +422,7 @@ Django offers another shortcut in this department. Run the command inclusion in the admin index template. It's a useful starting point. For full details on customizing the look and feel of the Django admin site in -general, see the `Django admin CSS guide`_. +general, see the :doc:`Django admin CSS guide <admin_css>`. -When you're comfortable with the admin site, read `part 3 of this tutorial`_ to +When you're comfortable with the admin site, read :doc:`part 3 of this tutorial <tutorial03>` to start working on public poll views. - -.. _Django admin CSS guide: http://www.djangoproject.com/documentation/admin_css/ -.. _part 3 of this tutorial: http://www.djangoproject.com/documentation/tutorial3/ diff --git a/docs/tutorial03.txt b/docs/tutorial03.txt index 248d234043ea..a3419bc360d2 100644 --- a/docs/tutorial03.txt +++ b/docs/tutorial03.txt @@ -2,11 +2,9 @@ Writing your first Django app, part 3 ===================================== -This tutorial begins where `Tutorial 2`_ left off. We're continuing the Web-poll +This tutorial begins where :doc:`Tutorial 2 <tutorial02>` left off. We're continuing the Web-poll application and will focus on creating the public interface -- "views." -.. _Tutorial 2: http://www.djangoproject.com/documentation/tutorial2/ - Philosophy ========== @@ -57,8 +55,8 @@ When it finds a match, Django calls the Python callback function, with an regular expression as keyword arguments, and, optionally, arbitrary keyword arguments from the dictionary (an optional third item in the tuple). -For more on ``HTTPRequest`` objects, see the `request and response documentation`_. -For more details on URLconfs, see the `URLconf documentation`_. +For more on ``HTTPRequest`` objects, see the :doc:`request and response documentation <request_response>`. +For more details on URLconfs, see the :doc:`URLconf documentation <url_dispatch>`. When you ran ``python manage.py startproject mysite`` at the beginning of Tutorial 1, it created a default URLconf in ``mysite/urls.py``. It also @@ -117,8 +115,6 @@ time the URLconf module is loaded. They're super fast. .. _Wikipedia's entry: http://en.wikipedia.org/wiki/Regular_expression .. _Python documentation: http://www.python.org/doc/current/lib/module-re.html -.. _request and response documentation: http://www.djangoproject.com/documentation/request_response/ -.. _URLconf documentation: http://www.djangoproject.com/documentation/url_dispatch/ Write your first view ===================== @@ -375,9 +371,7 @@ Method-calling happens in the ``{% for %}`` loop: ``poll.choice_set.all`` is interpreted as the Python code ``poll.choice_set.all()``, which returns an iterable of Choice objects and is suitable for use in the ``{% for %}`` tag. -See the `template guide`_ for full details on how templates work. - -.. _template guide: http://www.djangoproject.com/documentation/templates/ +See the :doc:`template guide <templates>` for full details on how templates work. Simplifying the URLconfs ======================== @@ -461,7 +455,5 @@ other URL root, and the app will still work. All the poll app cares about is its relative URLs, not its absolute URLs. -When you're comfortable with writing views, read `part 4 of this tutorial`_ to +When you're comfortable with writing views, read :doc:`part 4 of this tutorial <tutorial04>` to learn about simple form processing and generic views. - -.. _part 4 of this tutorial: http://www.djangoproject.com/documentation/tutorial4/ diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt index f234ed0ce163..c3d72a855737 100644 --- a/docs/tutorial04.txt +++ b/docs/tutorial04.txt @@ -2,7 +2,7 @@ Writing your first Django app, part 4 ===================================== -This tutorial begins where `Tutorial 3`_ left off. We're continuing the Web-poll +This tutorial begins where :doc:`Tutorial3 <tutorial03>` left off. We're continuing the Web-poll application and will focus on simple form processing and cutting down our code. Write a simple form @@ -39,7 +39,7 @@ A quick rundown: Django; it's just good Web development practice. Now, let's create a Django view that handles the submitted data and does -something with it. Remember, in `Tutorial 3`_, we created a URLconf for the +something with it. Remember, in :doc:`Tutorial3 <tutorial03>`, we created a URLconf for the polls application that includes this line:: (r'^(?P<poll_id>\d+)/vote/$', 'mysite.polls.views.vote'), @@ -94,7 +94,7 @@ This code includes a few things we haven't covered yet in this tutorial: tip isn't specific to Django; it's just good Web development practice. As mentioned in Tutorial 3, ``request`` is a ``HTTPRequest`` object. For more -on ``HTTPRequest`` objects, see the `request and response documentation`_. +on ``HTTPRequest`` objects, see the :doc:`request and response documentation <request_response>`. After somebody votes in a poll, the ``vote()`` view redirects to the results page for the poll. Let's write that view:: @@ -103,7 +103,7 @@ page for the poll. Let's write that view:: p = get_object_or_404(Poll, pk=poll_id) return render_to_response('polls/results.html', {'poll': p}) -This is almost exactly the same as the ``detail()`` view from `Tutorial 3`_. +This is almost exactly the same as the ``detail()`` view from :doc:`Tutorial3 <tutorial03>`. The only difference is the template name. We'll fix this redundancy later. Now, create a ``results.html`` template:: @@ -120,12 +120,10 @@ Now, go to ``/polls/1/`` in your browser and vote in the poll. You should see a results page that gets updated each time you vote. If you submit the form without having chosen a choice, you should see the error message. -.. _request and response documentation: http://www.djangoproject.com/documentation/request_response/ - Use generic views: Less code is better ====================================== -The ``detail()`` (from `Tutorial 3`_) and ``results()`` views are stupidly +The ``detail()`` (from :doc:`Tutorial3 <tutorial03>`) and ``results()`` views are stupidly simple -- and, as mentioned above, redundant. The ``index()`` view (also from Tutorial 3), which displays a list of polls, is similar. @@ -224,9 +222,7 @@ context instead of ``poll``. Run the server, and use your new polling app based on generic views. -For full details on generic views, see the `generic views documentation`_. - -.. _generic views documentation: http://www.djangoproject.com/documentation/generic_views/ +For full details on generic views, see the :doc:`generic views documentation <generic_views>`. Coming soon =========== @@ -240,5 +236,3 @@ installments: * Using the comments framework * Advanced admin features: Permissions * Advanced admin features: Custom JavaScript - -.. _Tutorial 3: http://www.djangoproject.com/documentation/tutorial3/ diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt index 498a906d5e68..dc2da81a9ff3 100644 --- a/docs/url_dispatch.txt +++ b/docs/url_dispatch.txt @@ -32,7 +32,7 @@ How Django processes a request When a user requests a page from your Django-powered site, this is the algorithm the system follows to determine which Python code to execute: - 1. Django looks at the ``ROOT_URLCONF`` setting in your `settings file`_. + 1. Django looks at the ``ROOT_URLCONF`` setting in your :doc:`settings file <settings>`. This should be a string representing the full Python import path to your URLconf. For example: ``"mydjangoapps.urls"``. 2. Django loads that Python module and looks for the variable @@ -42,12 +42,9 @@ algorithm the system follows to determine which Python code to execute: one that matches the requested URL. 4. Once one of the regexes matches, Django imports and calls the given view, which is a simple Python function. The view gets passed a - `request object`_ as its first argument and any values captured in the + :doc:`request object <request_response>` as its first argument and any values captured in the regex as remaining arguments. -.. _settings file: http://www.djangoproject.com/documentation/settings/ -.. _request object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects - Example ======= @@ -258,7 +255,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 `Django overview`_:: +Here's the example URLconf from the :doc:`Django overview <overview>`:: from django.conf.urls.defaults import * @@ -286,8 +283,6 @@ With this in mind, the above example can be written more concisely as:: Note that you don't put a trailing dot (``"."``) in the prefix. Django puts that in automatically. -.. _Django overview: http://www.djangoproject.com/documentation/overview/ - Multiple view prefixes ---------------------- @@ -384,8 +379,5 @@ In this example, for a request to ``/blog/2005/``, Django will call the year='2005', foo='bar' -This technique is used in `generic views`_ and in the `syndication framework`_ +This technique is used in :doc:`generic views <generic_views>` and in the :doc:`syndication framework <syndication_feeds>` to pass metadata and options to views. - -.. _generic views: http://www.djangoproject.com/documentation/generic_views/ -.. _syndication framework: http://www.djangoproject.com/documentation/syndication/