Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.2.X] Fixed #14141: docs now use the :doc: construct for links betw…

…een documents.

Thanks, Ramiro Morales.

Backport of [13608] from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@13609 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 936203434e0db40c94556c50e49c6c531e4628fb 1 parent c9016c1
Jacob Kaplan-Moss jacobian authored
Showing with 1,222 additions and 1,523 deletions.
  1. +3 −3 docs/_ext/djangodocs.py
  2. +2 −4 docs/faq/admin.txt
  3. +1 −3 docs/faq/contributing.txt
  4. +4 −6 docs/faq/general.txt
  5. +0 −2  docs/faq/help.txt
  6. +0 −2  docs/faq/index.txt
  7. +4 −6 docs/faq/install.txt
  8. +2 −4 docs/faq/models.txt
  9. +0 −2  docs/faq/usage.txt
  10. +16 −16 docs/glossary.txt
  11. +1 −3 docs/howto/apache-auth.txt
  12. +0 −2  docs/howto/auth-remote-user.txt
  13. +2 −4 docs/howto/custom-file-storage.txt
  14. +3 −5 docs/howto/custom-management-commands.txt
  15. +12 −14 docs/howto/custom-model-fields.txt
  16. +2 −4 docs/howto/custom-template-tags.txt
  17. +3 −5 docs/howto/deployment/fastcgi.txt
  18. +4 −6 docs/howto/deployment/index.txt
  19. +4 −6 docs/howto/deployment/modpython.txt
  20. +0 −2  docs/howto/deployment/modwsgi.txt
  21. +2 −4 docs/howto/error-reporting.txt
  22. +1 −3 docs/howto/i18n.txt
  23. +1 −3 docs/howto/index.txt
  24. +7 −9 docs/howto/initial-data.txt
  25. +0 −2  docs/howto/jython.txt
  26. +1 −3 docs/howto/legacy-databases.txt
  27. +2 −4 docs/howto/outputting-csv.txt
  28. +1 −3 docs/howto/outputting-pdf.txt
  29. +2 −4 docs/howto/static-files.txt
  30. +104 −104 docs/index.txt
  31. +0 −2  docs/internals/committers.txt
  32. +10 −12 docs/internals/contributing.txt
  33. +1 −3 docs/internals/deprecation.txt
  34. +38 −12 docs/internals/documentation.txt
  35. +0 −2  docs/internals/index.txt
  36. +0 −2  docs/internals/release-process.txt
  37. +7 −9 docs/internals/svn.txt
  38. +0 −2  docs/intro/index.txt
  39. +10 −12 docs/intro/install.txt
  40. +12 −14 docs/intro/overview.txt
  41. +20 −22 docs/intro/tutorial01.txt
  42. +3 −5 docs/intro/tutorial02.txt
  43. +7 −9 docs/intro/tutorial03.txt
  44. +10 −12 docs/intro/tutorial04.txt
  45. +16 −18 docs/intro/whatsnext.txt
  46. +28 −30 docs/misc/api-stability.txt
  47. +0 −2  docs/misc/design-philosophies.txt
  48. +0 −2  docs/misc/distributions.txt
  49. +0 −2  docs/misc/index.txt
  50. +0 −2  docs/obsolete/admin-css.txt
  51. +0 −2  docs/obsolete/index.txt
  52. +3 −5 docs/ref/authbackends.txt
  53. +1 −3 docs/ref/contrib/admin/actions.txt
  54. +10 −12 docs/ref/contrib/admin/index.txt
  55. +1 −3 docs/ref/contrib/auth.txt
  56. +0 −2  docs/ref/contrib/comments/custom.txt
  57. +9 −11 docs/ref/contrib/comments/example.txt
  58. +2 −4 docs/ref/contrib/comments/forms.txt
  59. +6 −8 docs/ref/contrib/comments/index.txt
  60. +30 −32 docs/ref/contrib/comments/models.txt
  61. +0 −2  docs/ref/contrib/comments/moderation.txt
  62. +2 −4 docs/ref/contrib/comments/settings.txt
  63. +3 −5 docs/ref/contrib/comments/signals.txt
  64. +3 −5 docs/ref/contrib/comments/upgrade.txt
  65. +3 −5 docs/ref/contrib/contenttypes.txt
  66. +0 −2  docs/ref/contrib/csrf.txt
  67. +7 −9 docs/ref/contrib/databrowse.txt
  68. +4 −6 docs/ref/contrib/flatpages.txt
  69. +0 −2  docs/ref/contrib/formtools/form-preview.txt
  70. +3 −5 docs/ref/contrib/formtools/form-wizard.txt
  71. +0 −2  docs/ref/contrib/formtools/index.txt
  72. +1 −1  docs/ref/contrib/gis/admin.txt
  73. +1 −1  docs/ref/contrib/gis/commands.txt
  74. +22 −22 docs/ref/contrib/gis/db-api.txt
  75. +2 −2 docs/ref/contrib/gis/deployment.txt
  76. +4 −6 docs/ref/contrib/gis/feeds.txt
  77. +55 −55 docs/ref/contrib/gis/geoquerysets.txt
  78. +102 −102 docs/ref/contrib/gis/install.txt
  79. +46 −46 docs/ref/contrib/gis/layermapping.txt
  80. +11 −11 docs/ref/contrib/gis/measure.txt
  81. +20 −20 docs/ref/contrib/gis/model-api.txt
  82. +1 −1  docs/ref/contrib/gis/testing.txt
  83. +53 −53 docs/ref/contrib/gis/tutorial.txt
  84. +0 −2  docs/ref/contrib/humanize.txt
  85. +20 −22 docs/ref/contrib/index.txt
  86. +2 −4 docs/ref/contrib/localflavor.txt
  87. +6 −8 docs/ref/contrib/messages.txt
  88. +4 −6 docs/ref/contrib/redirects.txt
  89. +6 −8 docs/ref/contrib/sitemaps.txt
  90. +3 −5 docs/ref/contrib/sites.txt
  91. +8 −10 docs/ref/contrib/syndication.txt
  92. +2 −4 docs/ref/contrib/webdesign.txt
  93. +2 −4 docs/ref/databases.txt
  94. +11 −13 docs/ref/django-admin.txt
  95. +0 −2  docs/ref/exceptions.txt
  96. +2 −4 docs/ref/files/file.txt
  97. +0 −2  docs/ref/files/index.txt
  98. +0 −2  docs/ref/files/storage.txt
  99. +2 −4 docs/ref/forms/api.txt
  100. +4 −6 docs/ref/forms/fields.txt
  101. +1 −3 docs/ref/forms/index.txt
  102. +0 −2  docs/ref/forms/validation.txt
  103. +0 −2  docs/ref/forms/widgets.txt
  104. +14 −16 docs/ref/generic-views.txt
  105. +0 −2  docs/ref/index.txt
  106. +11 −13 docs/ref/middleware.txt
  107. +9 −11 docs/ref/models/fields.txt
  108. +1 −3 docs/ref/models/index.txt
  109. +11 −13 docs/ref/models/instances.txt
  110. +0 −2  docs/ref/models/options.txt
  111. +10 −12 docs/ref/models/querysets.txt
  112. +0 −2  docs/ref/models/relations.txt
  113. +4 −6 docs/ref/request-response.txt
  114. +45 −47 docs/ref/settings.txt
  115. +6 −8 docs/ref/signals.txt
  116. +8 −10 docs/ref/templates/api.txt
  117. +5 −7 docs/ref/templates/builtins.txt
  118. +1 −3 docs/ref/templates/index.txt
  119. +1 −3 docs/ref/unicode.txt
  120. +2 −4 docs/ref/utils.txt
  121. +2 −4 docs/ref/validators.txt
  122. +1 −3 docs/releases/0.95.txt
  123. +0 −2  docs/releases/0.96.txt
  124. +3 −5 docs/releases/1.0-alpha-1.txt
  125. +7 −9 docs/releases/1.0-alpha-2.txt
  126. +11 −13 docs/releases/1.0-beta-2.txt
  127. +6 −8 docs/releases/1.0-beta.txt
  128. +6 −6 docs/releases/1.0-porting-guide.txt
  129. +0 −2  docs/releases/1.0.1.txt
  130. +2 −4 docs/releases/1.0.2.txt
  131. +16 −18 docs/releases/1.0.txt
  132. +10 −12 docs/releases/1.1-alpha-1.txt
  133. +9 −11 docs/releases/1.1-beta-1.txt
  134. +3 −5 docs/releases/1.1-rc-1.txt
  135. +1 −3 docs/releases/1.1.2.txt
  136. +20 −22 docs/releases/1.1.txt
  137. +12 −14 docs/releases/1.2-alpha-1.txt
  138. +7 −9 docs/releases/1.2-beta-1.txt
  139. +4 −6 docs/releases/1.2-rc-1.txt
  140. +30 −32 docs/releases/1.2.txt
  141. +0 −2  docs/releases/index.txt
  142. +18 −20 docs/topics/auth.txt
  143. +2 −4 docs/topics/cache.txt
  144. +0 −2  docs/topics/conditional-view-processing.txt
  145. +2 −4 docs/topics/db/aggregation.txt
  146. +0 −2  docs/topics/db/index.txt
  147. +2 −4 docs/topics/db/managers.txt
  148. +8 −10 docs/topics/db/models.txt
  149. +0 −2  docs/topics/db/multi-db.txt
  150. +8 −10 docs/topics/db/optimization.txt
  151. +4 −6 docs/topics/db/queries.txt
  152. +2 −4 docs/topics/db/sql.txt
  153. +1 −3 docs/topics/db/transactions.txt
  154. +0 −2  docs/topics/email.txt
  155. +4 −6 docs/topics/files.txt
  156. +0 −1  docs/topics/forms/formsets.txt
  157. +6 −8 docs/topics/forms/index.txt
  158. +0 −2  docs/topics/forms/media.txt
  159. +3 −5 docs/topics/forms/modelforms.txt
  160. +4 −6 docs/topics/generic-views.txt
  161. +2 −4 docs/topics/http/file-uploads.txt
  162. +1 −3 docs/topics/http/generic-views.txt
  163. +0 −2  docs/topics/http/index.txt
  164. +6 −8 docs/topics/http/middleware.txt
  165. +4 −6 docs/topics/http/sessions.txt
  166. +0 −2  docs/topics/http/shortcuts.txt
  167. +3 −5 docs/topics/http/urls.txt
  168. +1 −3 docs/topics/http/views.txt
  169. +2 −4 docs/topics/i18n/deployment.txt
  170. +3 −5 docs/topics/i18n/index.txt
  171. +2 −4 docs/topics/i18n/internationalization.txt
  172. +1 −3 docs/topics/i18n/localization.txt
  173. +0 −2  docs/topics/index.txt
  174. +10 −12 docs/topics/install.txt
  175. +0 −2  docs/topics/pagination.txt
  176. +0 −2  docs/topics/serialization.txt
  177. +3 −5 docs/topics/settings.txt
  178. +3 −5 docs/topics/signals.txt
  179. +9 −11 docs/topics/templates.txt
  180. +6 −8 docs/topics/testing.txt
6 docs/_ext/djangodocs.py
View
@@ -78,11 +78,11 @@ def run(self):
ret.append(node)
if not is_nextversion:
if len(self.arguments) == 1:
- linktext = 'Please, see the release notes <releases-%s>' % (arg0)
+ linktext = 'Please, see the release notes </releases/%s>' % (arg0)
try:
- xrefs = roles.XRefRole()('std:ref', linktext, linktext, self.lineno, self.state) # Sphinx >= 1.0
+ xrefs = roles.XRefRole()('doc', linktext, linktext, self.lineno, self.state) # Sphinx >= 1.0
except AttributeError:
- xrefs = roles.xfileref_role('ref', linktext, linktext, self.lineno, self.state) # Sphinx < 1.0
+ xrefs = roles.xfileref_role('doc', linktext, linktext, self.lineno, self.state) # Sphinx < 1.0
node.extend(xrefs[0])
node['version'] = arg0
else:
6 docs/faq/admin.txt
View
@@ -1,5 +1,3 @@
-.. _faq-admin:
-
FAQ: The admin
==============
@@ -32,7 +30,7 @@ How can I prevent the cache middleware from caching the admin site?
-------------------------------------------------------------------
Set the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` setting to ``True``. See the
-:ref:`cache documentation <topics-cache>` for more information.
+:doc:`cache documentation </topics/cache>` for more information.
How do I automatically set a field's value to the user who last edited the object in the admin?
-----------------------------------------------------------------------------------------------
@@ -91,5 +89,5 @@ 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
-:ref:`guide to the CSS used in the admin <obsolete-admin-css>` to get you started.
+:doc:`guide to the CSS used in the admin </obsolete/admin-css>` to get you started.
4 docs/faq/contributing.txt
View
@@ -1,5 +1,3 @@
-.. _faq-contributing:
-
FAQ: Contributing code
======================
@@ -7,7 +5,7 @@ How can I get started contributing code to Django?
--------------------------------------------------
Thanks for asking! We've written an entire document devoted to this question.
-It's titled :ref:`Contributing to Django <internals-contributing>`.
+It's titled :doc:`Contributing to Django </internals/contributing>`.
I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch?
--------------------------------------------------------------------------------------------
10 docs/faq/general.txt
View
@@ -1,5 +1,3 @@
-.. _faq-general:
-
FAQ: General
============
@@ -63,15 +61,15 @@ 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
-:ref:`cache framework <topics-cache>`.
+:doc:`cache framework </topics/cache>`.
Who's behind this?
------------------
Django was originally developed at World Online, the Web department of a
newspaper in Lawrence, Kansas, USA. Django's now run by an international team of
-volunteers; you can read all about them over at the :ref:`list of committers
-<internals-committers>`
+volunteers; you can read all about them over at the :doc:`list of committers
+</internals/committers>`
Which sites use Django?
-----------------------
@@ -146,7 +144,7 @@ philosophies 100%.
Like we said: We're picky.
We've documented our philosophies on the
-:ref:`design philosophies page <misc-design-philosophies>`.
+:doc:`design philosophies page </misc/design-philosophies>`.
Is Django a content-management-system (CMS)?
--------------------------------------------
2  docs/faq/help.txt
View
@@ -1,5 +1,3 @@
-.. _faq-help:
-
FAQ: Getting Help
=================
2  docs/faq/index.txt
View
@@ -1,5 +1,3 @@
-.. _faq-index:
-
==========
Django FAQ
==========
10 docs/faq/install.txt
View
@@ -1,5 +1,3 @@
-.. _faq-install:
-
FAQ: Installation
=================
@@ -7,9 +5,9 @@ How do I get started?
---------------------
#. `Download the code`_.
- #. Install Django (read the :ref:`installation guide <intro-install>`).
- #. Walk through the :ref:`tutorial <intro-tutorial01>`.
- #. Check out the rest of the :ref:`documentation <index>`, and `ask questions`_ if you
+ #. Install Django (read the :doc:`installation guide </intro/install>`).
+ #. Walk through the :doc:`tutorial </intro/tutorial01>`.
+ #. Check out the rest of the :doc:`documentation </index>`, and `ask questions`_ if you
run into trouble.
.. _`Download the code`: http://www.djangoproject.com/download/
@@ -26,7 +24,7 @@ For a development environment -- if you just want to experiment with Django --
you don't need to have a separate Web server installed; Django comes with its
own lightweight development server. For a production environment, Django
follows the WSGI_ spec, which means it can run on a variety of server
-platforms. See :ref:`Deploying Django <howto-deployment-index>` for some
+platforms. See :doc:`Deploying Django </howto/deployment/index>` for some
popular alternatives. Also, the `server arrangements wiki page`_ contains
details for several deployment strategies.
6 docs/faq/models.txt
View
@@ -1,5 +1,3 @@
-.. _faq-models:
-
FAQ: Databases and models
=========================
@@ -30,7 +28,7 @@ backend, and not all backends provide a way to retrieve the SQL after quoting.
.. versionadded:: 1.2
-If you are using :ref:`multiple databases<topics-db-multi-db>`, you can use the
+If you are using :doc:`multiple databases</topics/db/multi-db>`, you can use the
same interface on each member of the ``connections`` dictionary::
>>> from django.db import connections
@@ -39,7 +37,7 @@ same interface on each member of the ``connections`` dictionary::
Can I use Django with a pre-existing database?
----------------------------------------------
-Yes. See :ref:`Integrating with a legacy database <howto-legacy-databases>`.
+Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`.
If I make changes to a model, how do I update the database?
-----------------------------------------------------------
2  docs/faq/usage.txt
View
@@ -1,5 +1,3 @@
-.. _faq-usage:
-
FAQ: Using Django
=================
32 docs/glossary.txt
View
@@ -9,19 +9,19 @@ Glossary
field
An attribute on a :term:`model`; a given field usually maps directly to
a single database column.
-
- See :ref:`topics-db-models`.
+
+ See :doc:`/topics/db/models`.
generic view
A higher-order :term:`view` function that provides an abstract/generic
implementation of a common idiom or pattern found in view development.
-
- See :ref:`ref-generic-views`.
+
+ See :doc:`/ref/generic-views`.
model
Models store your application's data.
-
- See :ref:`topics-db-models`.
+
+ See :doc:`/topics/db/models`.
MTV
See :ref:`mtv`.
@@ -41,7 +41,7 @@ Glossary
property
Also known as "managed attributes", and a feature of Python since
version 2.2. From `the property documentation`__:
-
+
Properties are a neat way to implement attributes whose usage
resembles attribute access, but whose implementation uses method
calls. [...] You
@@ -56,26 +56,26 @@ Glossary
queryset
An object representing some set of rows to be fetched from the database.
-
- See :ref:`topics-db-queries`.
+
+ See :doc:`/topics/db/queries`.
slug
A short label for something, containing only letters, numbers,
underscores or hyphens. They're generally used in URLs. For
example, in a typical blog entry URL:
-
+
.. parsed-literal::
-
+
http://www.djangoproject.com/weblog/2008/apr/12/**spring**/
-
+
the last bit (``spring``) is the slug.
template
A chunk of text that acts as formatting for representing data. A
template helps to abstract the presentation of data from the data
itself.
-
- See :ref:`topics-templates`.
-
+
+ See :doc:`/topics/templates`.
+
view
- A function responsible for rending a page.
+ A function responsible for rending a page.
4 docs/howto/apache-auth.txt
View
@@ -1,12 +1,10 @@
-.. _howto-apache-auth:
-
=========================================================
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
-:ref:`authentication system <topics-auth>` directly. For example, you
+:doc:`authentication system </topics/auth>` directly. For example, you
could:
* Serve static/media files directly from Apache only to authenticated users.
2  docs/howto/auth-remote-user.txt
View
@@ -1,5 +1,3 @@
-.. _howto-auth-remote-user:
-
====================================
Authentication using ``REMOTE_USER``
====================================
6 docs/howto/custom-file-storage.txt
View
@@ -1,5 +1,3 @@
-.. _howto-custom-file-storage:
-
Writing a custom storage system
===============================
@@ -37,7 +35,7 @@ You'll need to follow these steps:
the ``path()`` method.
Your custom storage system may override any of the storage methods explained in
-:ref:`ref-files-storage`, but you **must** implement the following methods:
+:doc:`/ref/files/storage`, but you **must** implement the following methods:
* :meth:`Storage.delete`
* :meth:`Storage.exists`
@@ -63,7 +61,7 @@ backend storage system.
Called by ``Storage.save()``. The ``name`` will already have gone through
``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a
-``File`` object itself.
+``File`` object itself.
Should return the actual name of name of the file saved (usually the ``name``
passed in, but if the storage needs to change the file name return the new name
8 docs/howto/custom-management-commands.txt
View
@@ -1,5 +1,3 @@
-.. _howto-custom-management-commands:
-
====================================
Writing custom django-admin commands
====================================
@@ -10,7 +8,7 @@ Applications can register their own actions with ``manage.py``. For example,
you might want to add a ``manage.py`` action for a Django app that you're
distributing. In this document, we will be building a custom ``closepoll``
command for the ``polls`` application from the
-:ref:`tutorial<intro-tutorial01>`.
+:doc:`tutorial</intro/tutorial01>`.
To do this, just add a ``management/commands`` directory to the application.
Each Python module in that directory will be auto-discovered and registered as
@@ -70,7 +68,7 @@ The new custom command can be called using ``python manage.py closepoll
The ``handle()`` method takes zero or more ``poll_ids`` and sets ``poll.opened``
to ``False`` for each one. If the user referenced any nonexistant polls, a
:class:`CommandError` is raised. The ``poll.opened`` attribute does not exist
-in the :ref:`tutorial<intro-tutorial01>` and was added to
+in the :doc:`tutorial</intro/tutorial01>` and was added to
``polls.models.Poll`` for this example.
The same ``closepoll`` could be easily modified to delete a given poll instead
@@ -92,7 +90,7 @@ must be added to :attr:`~BaseCommand.option_list` like this:
# ...
In addition to being able to add custom command line options, all
-:ref:`management commands<ref-django-admin>` can accept some
+:doc:`management commands</ref/django-admin>` can accept some
default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.
Command objects
26 docs/howto/custom-model-fields.txt
View
@@ -1,5 +1,3 @@
-.. _howto-custom-model-fields:
-
===========================
Writing custom model fields
===========================
@@ -10,7 +8,7 @@ Writing custom model fields
Introduction
============
-The :ref:`model reference <topics-db-models>` documentation explains how to use
+The :doc:`model reference </topics/db/models>` documentation explains how to use
Django's standard field classes -- :class:`~django.db.models.CharField`,
:class:`~django.db.models.DateField`, etc. For many purposes, those classes are
all you'll need. Sometimes, though, the Django version won't meet your precise
@@ -109,7 +107,7 @@ What does a field class do?
---------------------------
All of Django's fields (and when we say *fields* in this document, we always
-mean model fields and not :ref:`form fields <ref-forms-fields>`) are subclasses
+mean model fields and not :doc:`form fields </ref/forms/fields>`) are subclasses
of :class:`django.db.models.Field`. Most of the information that Django records
about a field is common to all fields -- name, help text, uniqueness and so
forth. Storing all that information is handled by ``Field``. We'll get into the
@@ -124,7 +122,7 @@ when the model class is created (the precise details of how this is done are
unimportant here). This is because the field classes aren't necessary when
you're just creating and modifying attributes. Instead, they provide the
machinery for converting between the attribute value and what is stored in the
-database or sent to the :ref:`serializer <topics-serialization>`.
+database or sent to the :doc:`serializer </topics/serialization>`.
Keep this in mind when creating your own custom fields. The Django ``Field``
subclass you write provides the machinery for converting between your Python
@@ -209,8 +207,8 @@ parameters:
* :attr:`~django.db.models.Field.default`
* :attr:`~django.db.models.Field.editable`
* :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
- not be serialized when the model is passed to Django's :ref:`serializers
- <topics-serialization>`. Defaults to ``True``.
+ not be serialized when the model is passed to Django's :doc:`serializers
+ </topics/serialization>`. Defaults to ``True``.
* :attr:`~django.db.models.Field.unique_for_date`
* :attr:`~django.db.models.Field.unique_for_month`
* :attr:`~django.db.models.Field.unique_for_year`
@@ -225,8 +223,8 @@ parameters:
inheritance. For advanced use only.
All of the options without an explanation in the above list have the same
-meaning they do for normal Django fields. See the :ref:`field documentation
-<ref-models-fields>` for examples and details.
+meaning they do for normal Django fields. See the :doc:`field documentation
+</ref/models/fields>` for examples and details.
The ``SubfieldBase`` metaclass
------------------------------
@@ -270,8 +268,8 @@ value. This means that whenever a value may be assigned to the field,
you need to ensure that it will be of the correct datatype, or that
you handle any exceptions.
-This is especially important if you use :ref:`ModelForms
-<topics-forms-modelforms>`. When saving a ModelForm, Django will use
+This is especially important if you use :doc:`ModelForms
+</topics/forms/modelforms>`. When saving a ModelForm, Django will use
form values to instantiate model instances. However, if the cleaned
form data can't be used as valid input to the field, the normal form
validation process will break.
@@ -611,8 +609,8 @@ All of the ``kwargs`` dictionary is passed directly to the form field's
:meth:`~django.forms.Field__init__` method. Normally, all you need to do is
set up a good default for the ``form_class`` argument and then delegate further
handling to the parent class. This might require you to write a custom form
-field (and even a form widget). See the :ref:`forms documentation
-<topics-forms-index>` for information about this, and take a look at the code in
+field (and even a form widget). See the :doc:`forms documentation
+</topics/forms/index>` for information about this, and take a look at the code in
:mod:`django.contrib.localflavor` for some examples of custom widgets.
Continuing our ongoing example, we can write the :meth:`formfield` method as::
@@ -721,7 +719,7 @@ Django provides a ``File`` class, which is used as a proxy to the file's
contents and operations. This can be subclassed to customize how the file is
accessed, and what methods are available. It lives at
``django.db.models.fields.files``, and its default behavior is explained in the
-:ref:`file documentation <ref-files-file>`.
+:doc:`file documentation </ref/files/file>`.
Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
told to use it. To do so, simply assign the new ``File`` subclass to the special
6 docs/howto/custom-template-tags.txt
View
@@ -1,5 +1,3 @@
-.. _howto-custom-template-tags:
-
================================
Custom template tags and filters
================================
@@ -7,8 +5,8 @@ Custom template tags and filters
Introduction
============
-Django's template system comes with a wide variety of :ref:`built-in
-tags and filters <ref-templates-builtins>` designed to address the
+Django's template system comes with a wide variety of :doc:`built-in
+tags and filters </ref/templates/builtins>` designed to address the
presentation logic needs of your application. Nevertheless, you may
find yourself needing functionality that is not covered by the core
set of template primitives. You can extend the template engine by
8 docs/howto/deployment/fastcgi.txt
View
@@ -1,13 +1,11 @@
-.. _howto-deployment-fastcgi:
-
============================================
How to use Django with FastCGI, SCGI, or AJP
============================================
.. highlight:: bash
-Although the current preferred setup for running Django is :ref:`Apache with
-mod_wsgi <howto-deployment-modwsgi>`, many people use shared hosting, on
+Although the current preferred setup for running Django is :doc:`Apache with
+mod_wsgi </howto/deployment/modwsgi>`, many people use shared hosting, on
which protocols such as FastCGI, SCGI or AJP are the only viable options. In
some setups, these protocols may provide better performance than mod_wsgi_.
@@ -74,7 +72,7 @@ TCP socket. What you choose is a manner of preference; a TCP socket is usually
easier due to permissions issues.
To start your server, first change into the directory of your project (wherever
-your :ref:`manage.py <ref-django-admin>` is), and then run the
+your :doc:`manage.py </ref/django-admin>` is), and then run the
:djadmin:`runfcgi` command::
./manage.py runfcgi [options]
10 docs/howto/deployment/index.txt
View
@@ -1,5 +1,3 @@
-.. _howto-deployment-index:
-
Deploying Django
================
@@ -10,18 +8,18 @@ ways to easily deploy Django:
.. toctree::
:maxdepth: 1
-
+
modwsgi
modpython
fastcgi
-
+
If you're new to deploying Django and/or Python, we'd recommend you try
-:ref:`mod_wsgi <howto-deployment-modwsgi>` first. In most cases it'll be the easiest,
+:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be the easiest,
fastest, and most stable deployment choice.
.. seealso::
* `Chapter 12 of The Django Book`_ discusses deployment and especially
scaling in more detail.
-
+
.. _chapter 12 of the django book: http://djangobook.com/en/2.0/chapter12/
10 docs/howto/deployment/modpython.txt
View
@@ -1,5 +1,3 @@
-.. _howto-deployment-modpython:
-
============================================
How to use Django with Apache and mod_python
============================================
@@ -8,7 +6,7 @@ How to use Django with Apache and mod_python
The `mod_python`_ module for Apache_ can be used to deploy Django to a
production server, although it has been mostly superseded by the simpler
-:ref:`mod_wsgi deployment option <howto-deployment-modwsgi>`.
+:doc:`mod_wsgi deployment option </howto/deployment/modwsgi>`.
mod_python is similar to (and inspired by) `mod_perl`_ : It embeds Python within
Apache and loads Python code into memory when the server starts. Code stays in
@@ -25,8 +23,8 @@ Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
Apache, there's no better source than `Apache's own official
documentation`_
- * You may also be interested in :ref:`How to use Django with FastCGI, SCGI,
- or AJP <howto-deployment-fastcgi>`.
+ * You may also be interested in :doc:`How to use Django with FastCGI, SCGI,
+ or AJP </howto/deployment/fastcgi>`.
.. _Apache: http://httpd.apache.org/
.. _mod_python: http://www.modpython.org/
@@ -383,7 +381,7 @@ If you get a UnicodeEncodeError
===============================
If you're taking advantage of the internationalization features of Django (see
-:ref:`topics-i18n`) and you intend to allow users to upload files, you must
+:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must
ensure that the environment used to start Apache is configured to accept
non-ASCII file names. If your environment is not correctly configured, you
will trigger ``UnicodeEncodeError`` exceptions when calling functions like
2  docs/howto/deployment/modwsgi.txt
View
@@ -1,5 +1,3 @@
-.. _howto-deployment-modwsgi:
-
==========================================
How to use Django with Apache and mod_wsgi
==========================================
6 docs/howto/error-reporting.txt
View
@@ -1,5 +1,3 @@
-.. _howto-error-reporting:
-
Error reporting via e-mail
==========================
@@ -30,8 +28,8 @@ the HTTP request that caused the error.
to specify :setting:`EMAIL_HOST` and possibly
:setting:`EMAIL_HOST_USER` and :setting:`EMAIL_HOST_PASSWORD`,
though other settings may be also required depending on your mail
- server's configuration. Consult :ref:`the Django settings
- documentation <ref-settings>` for a full list of email-related
+ server's configuration. Consult :doc:`the Django settings
+ documentation </ref/settings>` for a full list of email-related
settings.
By default, Django will send email from root@localhost. However, some mail
4 docs/howto/i18n.txt
View
@@ -1,5 +1,3 @@
-.. _howto-i18n:
-
.. _using-translations-in-your-own-projects:
===============================================
@@ -46,7 +44,7 @@ To create message files, you use the :djadmin:`django-admin.py makemessages <mak
tool. You only need to be in the same directory where the ``locale/`` directory
is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>`
to produce the binary ``.mo`` files that are used by ``gettext``. Read the
-:ref:`topics-i18n-localization` document for more details.
+:doc:`/topics/i18n/localization` document for more details.
You can also run ``django-admin.py compilemessages --settings=path.to.settings``
to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
4 docs/howto/index.txt
View
@@ -1,11 +1,9 @@
-.. _howto-index:
-
"How-to" guides
===============
Here you'll find short answers to "How do I....?" types of questions. These
how-to guides don't cover topics in depth -- you'll find that material in the
-:ref:`topics-index` and the :ref:`ref-index`. However, these guides will help
+:doc:`/topics/index` and the :doc:`/ref/index`. However, these guides will help
you quickly accomplish common tasks.
.. toctree::
16 docs/howto/initial-data.txt
View
@@ -1,5 +1,3 @@
-.. _howto-initial-data:
-
=================================
Providing initial data for models
=================================
@@ -20,10 +18,10 @@ Providing initial data with fixtures
A fixture is a collection of data that Django knows how to import into a
database. The most straightforward way of creating a fixture if you've already
-got some data is to use the :djadmin:`manage.py dumpdata` command. Or, you can
-write fixtures by hand; fixtures can be written as XML, YAML, or JSON documents.
-The :ref:`serialization documentation <topics-serialization>` has more details
-about each of these supported :ref:`serialization formats
+got some data is to use the :djadmin:`manage.py dumpdata <dumpdata>` command.
+Or, you can write fixtures by hand; fixtures can be written as XML, YAML, or
+JSON documents. The :doc:`serialization documentation </topics/serialization>`
+has more details about each of these supported :ref:`serialization formats
<serialization-formats>`.
As an example, though, here's what a fixture for a simple ``Person`` model might
@@ -114,9 +112,9 @@ which will insert the desired data (e.g., properly-formatted
``INSERT`` statements separated by semicolons).
The SQL files are read by the :djadmin:`sqlcustom`, :djadmin:`sqlreset`,
-:djadmin:`sqlall` and :djadmin:`reset` commands in :ref:`manage.py
-<ref-django-admin>`. Refer to the :ref:`manage.py documentation
-<ref-django-admin>` for more information.
+:djadmin:`sqlall` and :djadmin:`reset` commands in :doc:`manage.py
+</ref/django-admin>`. Refer to the :doc:`manage.py documentation
+</ref/django-admin>` for more information.
Note that if you have multiple SQL data files, there's no guarantee of
the order in which they're executed. The only thing you can assume is
2  docs/howto/jython.txt
View
@@ -1,5 +1,3 @@
-.. _howto-jython:
-
========================
Running Django on Jython
========================
4 docs/howto/legacy-databases.txt
View
@@ -1,5 +1,3 @@
-.. _howto-legacy-databases:
-
=========================================
Integrating Django with a legacy database
=========================================
@@ -9,7 +7,7 @@ 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
-:ref:`tutorial <intro-tutorial01>`.
+:doc:`tutorial </intro/tutorial01>`.
Once you've got Django set up, you'll follow this general process to integrate
with an existing database.
6 docs/howto/outputting-csv.txt
View
@@ -1,5 +1,3 @@
-.. _howto-outputting-csv:
-
==========================
Outputting CSV with Django
==========================
@@ -61,7 +59,7 @@ mention:
Using the template system
=========================
-Alternatively, you can use the :ref:`Django template system <topics-templates>`
+Alternatively, you can use the :doc:`Django template system </topics/templates>`
to generate CSV. This is lower-level than using the convenient CSV, but the
solution is presented here for completeness.
@@ -113,4 +111,4 @@ Other text-based formats
Notice that there isn't very much specific to CSV here -- just the specific
output format. You can use either of these techniques to output any text-based
format you can dream of. You can also use a similar technique to generate
-arbitrary binary data; see :ref:`howto-outputting-pdf` for an example.
+arbitrary binary data; see :doc:`/howto/outputting-pdf` for an example.
4 docs/howto/outputting-pdf.txt
View
@@ -1,5 +1,3 @@
-.. _howto-outputting-pdf:
-
===========================
Outputting PDFs with Django
===========================
@@ -154,5 +152,5 @@ Other formats
Notice that there isn't a lot in these examples that's PDF-specific -- just the
bits using ``reportlab``. You can use a similar technique to generate any
arbitrary format that you can find a Python library for. Also see
-:ref:`howto-outputting-csv` for another example and some techniques you can use
+:doc:`/howto/outputting-csv` for another example and some techniques you can use
when generated text-based formats.
6 docs/howto/static-files.txt
View
@@ -1,5 +1,3 @@
-.. _howto-static-files:
-
=========================
How to serve static files
=========================
@@ -42,7 +40,7 @@ Here's the formal definition of the :func:`~django.views.static.serve` view:
.. function:: def serve(request, path, document_root, show_indexes=False)
-To use it, just put this in your :ref:`URLconf <topics-http-urls>`::
+To use it, just put this in your :doc:`URLconf </topics/http/urls>`::
(r'^site_media/(?P<path>.*)$', 'django.views.static.serve',
{'document_root': '/path/to/media'}),
@@ -71,7 +69,7 @@ required. For example, if we have a line in ``settings.py`` that says::
STATIC_DOC_ROOT = '/path/to/media'
-...we could write the above :ref:`URLconf <topics-http-urls>` entry as::
+...we could write the above :doc:`URLconf </topics/http/urls>` entry as::
from django.conf import settings
...
208 docs/index.txt
View
@@ -12,10 +12,10 @@ Getting help
Having trouble? We'd like to help!
-* Try the :ref:`FAQ <faq-index>` -- it's got answers to many common questions.
+* Try the :doc:`FAQ <faq/index>` -- it's got answers to many common questions.
* Looking for specific information? Try the :ref:`genindex`, :ref:`modindex` or
- the :ref:`detailed table of contents <contents>`.
+ the :doc:`detailed table of contents <contents>`.
* Search for information in the `archives of the django-users mailing list`_, or
`post a question`_.
@@ -35,179 +35,179 @@ First steps
===========
* **From scratch:**
- :ref:`Overview <intro-overview>` |
- :ref:`Installation <intro-install>`
+ :doc:`Overview <intro/overview>` |
+ :doc:`Installation <intro/install>`
* **Tutorial:**
- :ref:`Part 1 <intro-tutorial01>` |
- :ref:`Part 2 <intro-tutorial02>` |
- :ref:`Part 3 <intro-tutorial03>` |
- :ref:`Part 4 <intro-tutorial04>`
+ :doc:`Part 1 <intro/tutorial01>` |
+ :doc:`Part 2 <intro/tutorial02>` |
+ :doc:`Part 3 <intro/tutorial03>` |
+ :doc:`Part 4 <intro/tutorial04>`
The model layer
===============
* **Models:**
- :ref:`Model syntax <topics-db-models>` |
- :ref:`Field types <ref-models-fields>` |
- :ref:`Meta options <ref-models-options>`
+ :doc:`Model syntax <topics/db/models>` |
+ :doc:`Field types <ref/models/fields>` |
+ :doc:`Meta options <ref/models/options>`
* **QuerySets:**
- :ref:`Executing queries <topics-db-queries>` |
- :ref:`QuerySet method reference <ref-models-querysets>`
+ :doc:`Executing queries <topics/db/queries>` |
+ :doc:`QuerySet method reference <ref/models/querysets>`
* **Model instances:**
- :ref:`Instance methods <ref-models-instances>` |
- :ref:`Accessing related objects <ref-models-relations>`
+ :doc:`Instance methods <ref/models/instances>` |
+ :doc:`Accessing related objects <ref/models/relations>`
* **Advanced:**
- :ref:`Managers <topics-db-managers>` |
- :ref:`Raw SQL <topics-db-sql>` |
- :ref:`Transactions <topics-db-transactions>` |
- :ref:`Aggregation <topics-db-aggregation>` |
- :ref:`Custom fields <howto-custom-model-fields>` |
- :ref:`Multiple databases <topics-db-multi-db>`
+ :doc:`Managers <topics/db/managers>` |
+ :doc:`Raw SQL <topics/db/sql>` |
+ :doc:`Transactions <topics/db/transactions>` |
+ :doc:`Aggregation <topics/db/aggregation>` |
+ :doc:`Custom fields <howto/custom-model-fields>` |
+ :doc:`Multiple databases <topics/db/multi-db>`
* **Other:**
- :ref:`Supported databases <ref-databases>` |
- :ref:`Legacy databases <howto-legacy-databases>` |
- :ref:`Providing initial data <howto-initial-data>` |
- :ref:`Optimize database access <topics-db-optimization>`
+ :doc:`Supported databases <ref/databases>` |
+ :doc:`Legacy databases <howto/legacy-databases>` |
+ :doc:`Providing initial data <howto/initial-data>` |
+ :doc:`Optimize database access <topics/db/optimization>`
The template layer
==================
* **For designers:**
- :ref:`Syntax overview <topics-templates>` |
- :ref:`Built-in tags and filters <ref-templates-builtins>`
+ :doc:`Syntax overview <topics/templates>` |
+ :doc:`Built-in tags and filters <ref/templates/builtins>`
* **For programmers:**
- :ref:`Template API <ref-templates-api>` |
- :ref:`Custom tags and filters <howto-custom-template-tags>`
+ :doc:`Template API <ref/templates/api>` |
+ :doc:`Custom tags and filters <howto/custom-template-tags>`
The view layer
==============
* **The basics:**
- :ref:`URLconfs <topics-http-urls>` |
- :ref:`View functions <topics-http-views>` |
- :ref:`Shortcuts <topics-http-shortcuts>`
+ :doc:`URLconfs <topics/http/urls>` |
+ :doc:`View functions <topics/http/views>` |
+ :doc:`Shortcuts <topics/http/shortcuts>`
- * **Reference:** :ref:`Request/response objects <ref-request-response>`
+ * **Reference:** :doc:`Request/response objects <ref/request-response>`
* **File uploads:**
- :ref:`Overview <topics-http-file-uploads>` |
- :ref:`File objects <ref-files-file>` |
- :ref:`Storage API <ref-files-storage>` |
- :ref:`Managing files <topics-files>` |
- :ref:`Custom storage <howto-custom-file-storage>`
+ :doc:`Overview <topics/http/file-uploads>` |
+ :doc:`File objects <ref/files/file>` |
+ :doc:`Storage API <ref/files/storage>` |
+ :doc:`Managing files <topics/files>` |
+ :doc:`Custom storage <howto/custom-file-storage>`
* **Generic views:**
- :ref:`Overview<topics-generic-views>` |
- :ref:`Built-in generic views<ref-generic-views>`
+ :doc:`Overview<topics/generic-views>` |
+ :doc:`Built-in generic views<ref/generic-views>`
* **Advanced:**
- :ref:`Generating CSV <howto-outputting-csv>` |
- :ref:`Generating PDF <howto-outputting-pdf>`
+ :doc:`Generating CSV <howto/outputting-csv>` |
+ :doc:`Generating PDF <howto/outputting-pdf>`
* **Middleware:**
- :ref:`Overview <topics-http-middleware>` |
- :ref:`Built-in middleware classes <ref-middleware>`
+ :doc:`Overview <topics/http/middleware>` |
+ :doc:`Built-in middleware classes <ref/middleware>`
Forms
=====
* **The basics:**
- :ref:`Overview <topics-forms-index>` |
- :ref:`Form API <ref-forms-api>` |
- :ref:`Built-in fields <ref-forms-fields>` |
- :ref:`Built-in widgets <ref-forms-widgets>`
+ :doc:`Overview <topics/forms/index>` |
+ :doc:`Form API <ref/forms/api>` |
+ :doc:`Built-in fields <ref/forms/fields>` |
+ :doc:`Built-in widgets <ref/forms/widgets>`
* **Advanced:**
- :ref:`Forms for models <topics-forms-modelforms>` |
- :ref:`Integrating media <topics-forms-media>` |
- :ref:`Formsets <topics-forms-formsets>` |
- :ref:`Customizing validation <ref-forms-validation>`
+ :doc:`Forms for models <topics/forms/modelforms>` |
+ :doc:`Integrating media <topics/forms/media>` |
+ :doc:`Formsets <topics/forms/formsets>` |
+ :doc:`Customizing validation <ref/forms/validation>`
* **Extras:**
- :ref:`Form preview <ref-contrib-formtools-form-preview>` |
- :ref:`Form wizard <ref-contrib-formtools-form-wizard>`
+ :doc:`Form preview <ref/contrib/formtools/form-preview>` |
+ :doc:`Form wizard <ref/contrib/formtools/form-wizard>`
The development process
=======================
* **Settings:**
- :ref:`Overview <topics-settings>` |
- :ref:`Full list of settings <ref-settings>`
+ :doc:`Overview <topics/settings>` |
+ :doc:`Full list of settings <ref/settings>`
* **Exceptions:**
- :ref:`Overview <ref-exceptions>`
+ :doc:`Overview <ref/exceptions>`
* **django-admin.py and manage.py:**
- :ref:`Overview <ref-django-admin>` |
- :ref:`Adding custom commands <howto-custom-management-commands>`
+ :doc:`Overview <ref/django-admin>` |
+ :doc:`Adding custom commands <howto/custom-management-commands>`
- * **Testing:** :ref:`Overview <topics-testing>`
+ * **Testing:** :doc:`Overview <topics/testing>`
* **Deployment:**
- :ref:`Overview <howto-deployment-index>` |
- :ref:`Apache/mod_wsgi <howto-deployment-modwsgi>` |
- :ref:`Apache/mod_python <howto-deployment-modpython>` |
- :ref:`FastCGI/SCGI/AJP <howto-deployment-fastcgi>` |
- :ref:`Apache authentication <howto-apache-auth>` |
- :ref:`Serving static files <howto-static-files>` |
- :ref:`Tracking code errors by e-mail <howto-error-reporting>`
+ :doc:`Overview <howto/deployment/index>` |
+ :doc:`Apache/mod_wsgi <howto/deployment/modwsgi>` |
+ :doc:`Apache/mod_python <howto/deployment/modpython>` |
+ :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
+ :doc:`Apache authentication <howto/apache-auth>` |
+ :doc:`Serving static files <howto/static-files>` |
+ :doc:`Tracking code errors by e-mail <howto/error-reporting>`
Other batteries included
========================
- * :ref:`Admin site <ref-contrib-admin>` | :ref:`Admin actions <ref-contrib-admin-actions>`
- * :ref:`Authentication <topics-auth>`
- * :ref:`Cache system <topics-cache>`
- * :ref:`Conditional content processing <topics-conditional-processing>`
- * :ref:`Comments <ref-contrib-comments-index>` | :ref:`Moderation <ref-contrib-comments-moderation>` | :ref:`Custom comments <ref-contrib-comments-custom>`
- * :ref:`Content types <ref-contrib-contenttypes>`
- * :ref:`Cross Site Request Forgery protection <ref-contrib-csrf>`
- * :ref:`Databrowse <ref-contrib-databrowse>`
- * :ref:`E-mail (sending) <topics-email>`
- * :ref:`Flatpages <ref-contrib-flatpages>`
- * :ref:`GeoDjango <ref-contrib-gis>`
- * :ref:`Humanize <ref-contrib-humanize>`
- * :ref:`Internationalization <topics-i18n>`
- * :ref:`Jython support <howto-jython>`
- * :ref:`"Local flavor" <ref-contrib-localflavor>`
- * :ref:`Messages <ref-contrib-messages>`
- * :ref:`Pagination <topics-pagination>`
- * :ref:`Redirects <ref-contrib-redirects>`
- * :ref:`Serialization <topics-serialization>`
- * :ref:`Sessions <topics-http-sessions>`
- * :ref:`Signals <topics-signals>`
- * :ref:`Sitemaps <ref-contrib-sitemaps>`
- * :ref:`Sites <ref-contrib-sites>`
- * :ref:`Syndication feeds (RSS/Atom) <ref-contrib-syndication>`
- * :ref:`Unicode in Django <ref-unicode>`
- * :ref:`Web design helpers <ref-contrib-webdesign>`
- * :ref:`Validators <ref-validators>`
+ * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>`
+ * :doc:`Authentication <topics/auth>`
+ * :doc:`Cache system <topics/cache>`
+ * :doc:`Conditional content processing <topics/conditional-view-processing>`
+ * :doc:`Comments <ref/contrib/comments/index>` | :doc:`Moderation <ref/contrib/comments/moderation>` | :doc:`Custom comments <ref/contrib/comments/custom>`
+ * :doc:`Content types <ref/contrib/contenttypes>`
+ * :doc:`Cross Site Request Forgery protection <ref/contrib/csrf>`
+ * :doc:`Databrowse <ref/contrib/databrowse>`
+ * :doc:`E-mail (sending) <topics/email>`
+ * :doc:`Flatpages <ref/contrib/flatpages>`
+ * :doc:`GeoDjango <ref/contrib/gis/index>`
+ * :doc:`Humanize <ref/contrib/humanize>`
+ * :doc:`Internationalization <topics/i18n/index>`
+ * :doc:`Jython support <howto/jython>`
+ * :doc:`"Local flavor" <ref/contrib/localflavor>`
+ * :doc:`Messages <ref/contrib/messages>`
+ * :doc:`Pagination <topics/pagination>`
+ * :doc:`Redirects <ref/contrib/redirects>`
+ * :doc:`Serialization <topics/serialization>`
+ * :doc:`Sessions <topics/http/sessions>`
+ * :doc:`Signals <topics/signals>`
+ * :doc:`Sitemaps <ref/contrib/sitemaps>`
+ * :doc:`Sites <ref/contrib/sites>`
+ * :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>`
+ * :doc:`Unicode in Django <ref/unicode>`
+ * :doc:`Web design helpers <ref/contrib/webdesign>`
+ * :doc:`Validators <ref/validators>`
The Django open-source project
==============================
* **Community:**
- :ref:`How to get involved <internals-contributing>` |
- :ref:`The release process <internals-release-process>` |
- :ref:`Team of committers <internals-committers>` |
- :ref:`The Django source code repository <internals-svn>`
+ :doc:`How to get involved <internals/contributing>` |
+ :doc:`The release process <internals/release-process>` |
+ :doc:`Team of committers <internals/committers>` |
+ :doc:`The Django source code repository <internals/svn>`
* **Design philosophies:**
- :ref:`Overview <misc-design-philosophies>`
+ :doc:`Overview <misc/design-philosophies>`
* **Documentation:**
- :ref:`About this documentation <internals-documentation>`
+ :doc:`About this documentation <internals/documentation>`
* **Third-party distributions:**
- :ref:`Overview <misc-distributions>`
+ :doc:`Overview <misc/distributions>`
* **Django over time:**
- :ref:`API stability <misc-api-stability>` |
- :ref:`Release notes and upgrading instructions <releases-index>` |
- :ref:`Deprecation Timeline <internals-deprecation>`
+ :doc:`API stability <misc/api-stability>` |
+ :doc:`Release notes and upgrading instructions <releases/index>` |
+ :doc:`Deprecation Timeline <internals/deprecation>`
2  docs/internals/committers.txt
View
@@ -1,5 +1,3 @@
-.. _internals-committers:
-
=================
Django committers
=================
22 docs/internals/contributing.txt
View
@@ -1,5 +1,3 @@
-.. _internals-contributing:
-
======================
Contributing to Django
======================
@@ -42,7 +40,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 :ref:`FAQ <faq-index>` to see if your issue might be a well-known question.
+ * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might be a well-known question.
* **Do** `search the tracker`_ to see if your issue has already been filed.
@@ -398,7 +396,7 @@ Various parts of Django, such as the admin site and validation error messages,
are internationalized. This means they display different text depending on a
user's language setting. For this, Django uses the same internationalization
infrastructure available to Django applications described in the
-:ref:`i18n documentation<topics-i18n>`.
+:doc:`i18n documentation</topics/i18n/index>`.
These translations are contributed by Django users worldwide. If you find an
incorrect translation, or if you'd like to add a language that isn't yet
@@ -409,7 +407,7 @@ translated, here's what to do:
* Make sure you read the notes about :ref:`specialties-of-django-i18n`.
* Create translations using the methods described in the
- :ref:`localization documentation <topics-i18n-localization>`. For this
+ :doc:`localization documentation </topics/i18n/localization>`. For this
you will use the ``django-admin.py makemessages`` tool. In this
particular case it should be run from the top-level ``django`` directory
of the Django source tree.
@@ -535,8 +533,8 @@ 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 :ref:`i18n
- documentation <topics-i18n>` for details.
+ * Mark all strings for internationalization; see the :doc:`i18n
+ documentation </topics/i18n/index>` for details.
* In docstrings, use "action words" such as::
@@ -698,8 +696,8 @@ General improvements, or other changes to the APIs that should be emphasized
should use the ".. versionchanged:: X.Y" directive (with the same format as the
``versionadded`` mentioned above.
-There's a full page of information about the :ref:`Django documentation
-system <internals-documentation>` that you should read prior to working on the
+There's a full page of information about the :doc:`Django documentation
+system </internals/documentation>` that you should read prior to working on the
documentation.
Guidelines for ReST files
@@ -829,7 +827,7 @@ The tests cover:
We appreciate any and all contributions to the test suite!
The Django tests all use the testing infrastructure that ships with Django for
-testing applications. See :ref:`Testing Django applications <topics-testing>`
+testing applications. See :doc:`Testing Django applications </topics/testing>`
for an explanation of how to write new tests.
Running the unit tests
@@ -1017,8 +1015,8 @@ for feature branches:
public, please add the branch to the `Django branches`_ wiki page.
2. Feature branches using SVN have a higher bar. If you want a branch in SVN
- itself, you'll need a "mentor" among the :ref:`core committers
- <internals-committers>`. This person is responsible for actually creating
+ itself, you'll need a "mentor" among the :doc:`core committers
+ </internals/committers>`. This person is responsible for actually creating
the branch, monitoring your process (see below), and ultimately merging
the branch into trunk.
4 docs/internals/deprecation.txt
View
@@ -1,5 +1,3 @@
-.. _internals-deprecation:
-
===========================
Django Deprecation Timeline
===========================
@@ -52,7 +50,7 @@ their deprecation, as per the :ref:`Django deprecation policy
associated methods (``user.message_set.create()`` and
``user.get_and_delete_messages()``), which have
been deprecated since the 1.2 release, will be removed. The
- :ref:`messages framework <ref-contrib-messages>` should be used
+ :doc:`messages framework </ref/contrib/messages>` should be used
instead.
* Authentication backends need to support the ``obj`` parameter for
50 docs/internals/documentation.txt
View
@@ -1,5 +1,3 @@
-.. _internals-documentation:
-
How the Django documentation works
==================================
@@ -88,27 +86,55 @@ __ http://sphinx.pocoo.org/markup/desc.html
An example
----------
-For a quick example of how it all fits together, check this out:
+For a quick example of how it all fits together, consider this hypothetical
+example:
- * First, the ``ref/settings.txt`` document starts out like this::
+ * First, the ``ref/settings.txt`` document could have an overall layout
+ like this:
- .. _ref-settings:
+ .. code-block:: rst
- Available settings
- ==================
+ ========
+ Settings
+ ========
...
- * Next, if you look at the ``topics/settings.txt`` document, you can see how
- a link to ``ref/settings`` works::
+ .. _available-settings:
Available settings
==================
- For a full list of available settings, see the :ref:`settings reference
- <ref-settings>`.
+ ...
+
+ .. _deprecated-settings:
+
+ Deprecated settings
+ ===================
+
+ ...
+
+ * Next, the ``topics/settings.txt`` document could contain something like
+ this:
+
+ .. code-block:: rst
+
+ You can access a :ref:`listing of all available settings
+ <available-settings>`. For a list of deprecated settings see
+ :ref:`deprecated-settings`.
+
+ You can find both in the :doc:`settings reference document </ref/settings>`.
+
+ We use the Sphinx doc_ cross reference element when we want to link to
+ another document as a whole and the ref_ element when we want to link to
+ an arbitrary location in a document.
+
+.. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc
+.. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref
+
+ * Next, notice how the settings are annotated:
- * Next, notice how the settings (right now just the top few) are annotated::
+ .. code-block:: rst
.. setting:: ADMIN_FOR
2  docs/internals/index.txt
View
@@ -1,5 +1,3 @@
-.. _internals-index:
-
Django internals
================
2  docs/internals/release-process.txt
View
@@ -1,5 +1,3 @@
-.. _internals-release-process:
-
========================
Django's release process
========================
16 docs/internals/svn.txt
View
@@ -1,5 +1,3 @@
-.. _internals-svn:
-
=================================
The Django source code repository
=================================
@@ -87,8 +85,8 @@ the ``django`` module within your checkout.
If you're going to be working on Django's code (say, to fix a bug or
develop a new feature), you can probably stop reading here and move
-over to :ref:`the documentation for contributing to Django
-<internals-contributing>`, which covers things like the preferred
+over to :doc:`the documentation for contributing to Django
+</internals/contributing>`, which covers things like the preferred
coding style and how to generate and submit a patch.
@@ -129,20 +127,20 @@ part of Django itself, and so are no longer separately maintained:
object-relational mapper. This has been part of Django since the 1.0
release, as the bundled application ``django.contrib.gis``.
-* ``i18n``: Added :ref:`internationalization support <topics-i18n>` to
+* ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to
Django. This has been part of Django since the 0.90 release.
* ``magic-removal``: A major refactoring of both the internals and
public APIs of Django's object-relational mapper. This has been part
of Django since the 0.95 release.
-* ``multi-auth``: A refactoring of :ref:`Django's bundled
- authentication framework <topics-auth>` which added support for
+* ``multi-auth``: A refactoring of :doc:`Django's bundled
+ authentication framework </topics/auth>` which added support for
:ref:`authentication backends <authentication-backends>`. This has
been part of Django since the 0.95 release.
-* ``new-admin``: A refactoring of :ref:`Django's bundled
- administrative application <ref-contrib-admin>`. This became part of
+* ``new-admin``: A refactoring of :doc:`Django's bundled
+ administrative application </ref/contrib/admin/index>`. This became part of
Django as of the 0.91 release, but was superseded by another
refactoring (see next listing) prior to the Django 1.0 release.
2  docs/intro/index.txt
View
@@ -1,5 +1,3 @@
-.. _intro-index:
-
Getting started
===============
22 docs/intro/install.txt
View
@@ -1,10 +1,8 @@
-.. _intro-install:
-
Quick install guide
===================
Before you can use Django, you'll need to get it installed. We have a
-:ref:`complete installation guide <topics-install>` that covers all the
+:doc:`complete installation guide </topics/install>` that covers all the
possibilities; this guide will guide you to a simple, minimal installation
that'll work while you walk through the introduction.
@@ -14,7 +12,7 @@ Install Python
Being a Python Web framework, Django requires Python. It works with any Python
version from 2.4 to 2.7 (due to backwards
incompatibilities in Python 3.0, Django does not currently work with
-Python 3.0; see :ref:`the Django FAQ <faq-install>` for more
+Python 3.0; see :doc:`the Django FAQ </faq/install>` for more
information on supported Python versions and the 3.0 transition), but we recommend installing Python 2.5 or later. If you do so, you won't need to set up a database just yet: Python 2.5 or later includes a lightweight database called SQLite_.
.. _sqlite: http://sqlite.org/
@@ -25,17 +23,17 @@ probably already have it installed.
.. admonition:: Django on Jython
If you use Jython_ (a Python implementation for the Java platform), you'll
- need to follow a few additional steps. See :ref:`howto-jython` for details.
+ need to follow a few additional steps. See :doc:`/howto/jython` for details.
.. _jython: http://www.jython.org/
You can verify that Python's installed by typing ``python`` from your shell; you should see something like::
- Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17)
+ Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17)
[GCC 4.0.1 (Apple Inc. build 5465)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>
-
+
Set up a database
-----------------
@@ -57,18 +55,18 @@ Install Django
You've got three easy options to install Django:
- * Install a version of Django :ref:`provided by your operating system
- distribution <misc-distributions>`. This is the quickest option for those
+ * Install a version of Django :doc:`provided by your operating system
+ distribution </misc/distributions>`. This is the quickest option for those
who have operating systems that distribute Django.
* :ref:`Install an official release <installing-official-release>`. This
is the best approach for users who want a stable version number and aren't
concerned about running a slightly older version of Django.
-
+
* :ref:`Install the latest development version
<installing-development-version>`. This is best for users who want the
latest-and-greatest features and aren't afraid of running brand-new code.
-
+
.. warning::
If you do either of the first two steps, keep an eye out for parts of the
@@ -79,7 +77,7 @@ You've got three easy options to install Django:
That's it!
----------
-That's it -- you can now :ref:`move onto the tutorial <intro-tutorial01>`.
+That's it -- you can now :doc:`move onto the tutorial </intro/tutorial01>`.
26 docs/intro/overview.txt
View
@@ -1,5 +1,3 @@
-.. _intro-overview:
-
==================
Django at a glance
==================
@@ -11,8 +9,8 @@ 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 -- but we've got both! When you're ready to start a project, you can
-:ref:`start with the tutorial <intro-tutorial01>` or :ref:`dive right into more
-detailed documentation <topics-index>`.
+:doc:`start with the tutorial </intro/tutorial01>` or :doc:`dive right into more
+detailed documentation </topics/index>`.
Design your model
=================
@@ -21,7 +19,7 @@ Although you can use Django without a database, it comes with an
object-relational mapper in which you describe your database layout in Python
code.
-The :ref:`data-model syntax <topics-db-models>` offers many rich ways of
+The :doc:`data-model syntax </topics/db/models>` offers many rich ways of
representing your models -- so far, it's been solving two years' worth of
database-schema problems. Here's a quick example::
@@ -56,7 +54,7 @@ tables in your database for whichever tables don't already exist.
Enjoy the free API
==================
-With that, you've got a free, and rich, :ref:`Python API <topics-db-queries>` to
+With that, you've got a free, and rich, :doc:`Python API </topics/db/queries>` to
access your data. The API is created on the fly, no code generation necessary::
>>> from mysite.models import Reporter, Article
@@ -131,7 +129,7 @@ A dynamic admin interface: it's not just scaffolding -- it's the whole house
============================================================================
Once your models are defined, Django can automatically create a professional,
-production ready :ref:`administrative interface <ref-contrib-admin>` -- a Web
+production ready :doc:`administrative interface </ref/contrib/admin/index>` -- a Web
site that lets authenticated users add, change and delete objects. It's as easy
as registering your model in the admin site::
@@ -168,8 +166,8 @@ A clean, elegant URL scheme is an important detail in a high-quality Web
application. Django encourages beautiful URL design and doesn't put any cruft
in URLs, like ``.php`` or ``.asp``.
-To design URLs for an app, you create a Python module called a :ref:`URLconf
-<topics-http-urls>`. A table of contents for your app, it contains a simple mapping
+To design URLs for an app, you create a Python module called a :doc:`URLconf
+</topics/http/urls>`. A table of contents for your app, it contains a simple mapping
between URL patterns and Python callback functions. URLconfs also serve to
decouple URLs from Python code.
@@ -216,7 +214,7 @@ and renders the template with the retrieved data. Here's an example view for
a_list = Article.objects.filter(pub_date__year=year)
return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list})
-This example uses Django's :ref:`template system <topics-templates>`, which has
+This example uses Django's :doc:`template system </topics/templates>`, which has
several powerful features but strives to stay simple enough for non-programmers
to use.
@@ -307,17 +305,17 @@ This is just the surface
This has been only a quick overview of Django's functionality. Some more useful
features:
- * A :ref:`caching framework <topics-cache>` that integrates with memcached
+ * A :doc:`caching framework </topics/cache>` that integrates with memcached
or other backends.
- * A :ref:`syndication framework <ref-contrib-syndication>` that makes
+ * A :doc:`syndication framework </ref/contrib/syndication>` that makes
creating RSS and Atom feeds as easy as writing a small Python class.
* More sexy automatically-generated admin features -- this overview barely
scratched the surface.
-The next obvious steps are for you to `download Django`_, read :ref:`the
-tutorial <intro-tutorial01>` and join `the community`_. Thanks for your
+The next obvious steps are for you to `download Django`_, read :doc:`the
+tutorial </intro/tutorial01>` and join `the community`_. Thanks for your
interest!
.. _download Django: http://www.djangoproject.com/download/
42 docs/intro/tutorial01.txt
View
@@ -1,5 +1,3 @@
-.. _intro-tutorial01:
-
=====================================
Writing your first Django app, part 1
=====================================
@@ -14,7 +12,7 @@ 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 polls.
-We'll assume you have :ref:`Django installed <intro-install>` already. You can
+We'll assume you have :doc:`Django installed </intro/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.
@@ -47,8 +45,8 @@ create a ``mysite`` directory in your current directory.
you try to run ``django-admin.py startproject``. This is because, on
Unix-based systems like OS X, a file must be marked as "executable" before it
can be run as a program. To do this, open Terminal.app and navigate (using
- the ``cd`` command) to the directory where :ref:`django-admin.py
- <ref-django-admin>` is installed, then run the command
+ the ``cd`` command) to the directory where :doc:`django-admin.py
+ </ref/django-admin>` is installed, then run the command
``chmod +x django-admin.py``.
.. note::
@@ -58,11 +56,11 @@ create a ``mysite`` directory in your current directory.
``django`` (which will conflict with Django itself) or ``test`` (which
conflicts with a built-in Python package).
-:ref:`django-admin.py <ref-django-admin>` should be on your system path if you
+:doc:`django-admin.py </ref/django-admin>` should be on your system path if you
installed Django via ``python setup.py``. If it's not on your path, you can find
it in ``site-packages/django/bin``, where ```site-packages``` is a directory
-within your Python installation. Consider symlinking to :ref:`django-admin.py
-<ref-django-admin>` from some place on your path, such as
+within your Python installation. Consider symlinking to :doc:`django-admin.py
+</ref/django-admin>` from some place on your path, such as
:file:`/usr/local/bin`.
.. admonition:: Where should this code live?
@@ -93,14 +91,14 @@ These files are:
* :file:`manage.py`: A command-line utility that lets you interact with this
Django project in various ways. You can read all the details about
- :file:`manage.py` in :ref:`ref-django-admin`.
+ :file:`manage.py` in :doc:`/ref/django-admin`.
* :file:`settings.py`: Settings/configuration for this Django project.
- :ref:`topics-settings` will tell you all about how settings work.
+ :doc:`/topics/settings` will tell you all about how settings work.
* :file:`urls.py`: The URL declarations for this Django project; a "table of
contents" of your Django-powered site. You can read more about URLs in
- :ref:`topics-http-urls`.
+ :doc:`/topics/http/urls`.
.. _more about packages: http://docs.python.org/tutorial/modules.html#packages
@@ -473,7 +471,7 @@ added to your project since the last time you ran syncdb. :djadmin:`syncdb` can
be called as often as you like, and it will only ever create the tables that
don't exist.
-Read the :ref:`django-admin.py documentation <ref-django-admin>` for full
+Read the :doc:`django-admin.py documentation </ref/django-admin>` for full
information on what the ``manage.py`` utility can do.
Playing with the API
@@ -508,10 +506,10 @@ things:
set the ``DJANGO_SETTINGS_MODULE`` environment variable to
``mysite.settings``.
- For more information on all of this, see the :ref:`django-admin.py
- documentation <ref-django-admin>`.
+ For more information on all of this, see the :doc:`django-admin.py
+ documentation </ref/django-admin>`.
-Once you're in the shell, explore the :ref:`database API <topics-db-queries>`::
+Once you're in the shell, explore the :doc:`database API </topics/db/queries>`::
>>> from mysite.polls.models import Poll, Choice # Import the model classes we just wrote.
@@ -570,8 +568,8 @@ of this object. Let's fix that by editing the polls model (in the
models and don't see any change in how they're represented, you're most
likely using an old version of Django. (This version of the tutorial is
written for the latest development version of Django.) If you're using a
- Subversion checkout of Django's development version (see :ref:`the
- installation docs <topics-install>` for more information), you shouldn't have
+ Subversion checkout of Django's development version (see :doc:`the
+ installation docs </topics/install>` for more information), you shouldn't have
any problems.
If you want to stick with an older version of Django, you'll want to switch
@@ -693,9 +691,9 @@ Save these changes and start a new Python interactive shell by running
>>> c = p.choice_set.filter(choice__startswith='Just hacking')
>>> c.delete()
-For more information on model relations, see :ref:`Accessing related objects
-<ref-models-relations>`. For full details on the database API, see our
-:ref:`Database API reference <topics-db-queries>`.
+For more information on model relations, see :doc:`Accessing related objects
+</ref/models/relations>`. For full details on the database API, see our
+:doc:`Database API reference </topics/db/queries>`.
-When you're comfortable with the API, read :ref:`part 2 of this tutorial
-<intro-tutorial02>` to get Django's automatic admin working.
+When you're comfortable with the API, read :doc:`part 2 of this tutorial
+</intro/tutorial02>` to get Django's automatic admin working.
8 docs/intro/tutorial02.txt
View
@@ -1,10 +1,8 @@
-.. _intro-tutorial02:
-
=====================================
Writing your first Django app, part 2
=====================================
-This tutorial begins where :ref:`Tutorial 1 <intro-tutorial01>` left off. We're
+This tutorial begins where :doc:`Tutorial 1 </intro/tutorial01>` left off. We're
continuing the Web-poll application and will focus on Django's
automatically-generated admin site.
@@ -463,5 +461,5 @@ object-specific admin pages in whatever way you think is best. Again,
don't worry if you can't understand the template language -- we'll cover that
in more detail in Tutorial 3.
-When you're comfortable with the admin site, read :ref:`part 3 of this tutorial
-<intro-tutorial03>` to start working on public poll views.
+When you're comfortable with the admin site, read :doc:`part 3 of this tutorial
+</intro/tutorial03>` to start working on public poll views.
16 docs/intro/tutorial03.txt
View
@@ -1,10 +1,8 @@
-.. _intro-tutorial03:
-
=====================================
Writing your first Django app, part 3
=====================================
-This tutorial begins where :ref:`Tutorial 2 <intro-tutorial02>` left off. We're
+This tutorial begins where :doc:`Tutorial 2 </intro/tutorial02>` left off. We're
continuing the Web-poll application and will focus on creating the public
interface -- "views."
@@ -68,8 +66,8 @@ arbitrary keyword arguments from the dictionary (an optional third item in the
tuple).
For more on :class:`~django.http.HttpRequest` objects, see the
-:ref:`ref-request-response`. For more details on URLconfs, see the
-:ref:`topics-http-urls`.
+:doc:`/ref/request-response`. For more details on URLconfs, see the
+:doc:`/topics/http/urls`.
When you ran ``django-admin.py startproject mysite`` at the beginning of
Tutorial 1, it created a default URLconf in ``mysite/urls.py``. It also
@@ -205,7 +203,7 @@ you want, using whatever Python libraries you want.
All Django wants is that :class:`~django.http.HttpResponse`. Or an exception.
Because it's convenient, let's use Django's own database API, which we covered
-in :ref:`Tutorial 1 <intro-tutorial01>`. Here's one stab at the ``index()``
+in :doc:`Tutorial 1 </intro/tutorial01>`. Here's one stab at the ``index()``
view, which displays the latest 5 poll questions in the system, separated by
commas, according to publication date::
@@ -425,7 +423,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 :ref:`template guide <topics-templates>` for more about templates.
+See the :doc:`template guide </topics/templates>` for more about templates.
Simplifying the URLconfs
========================
@@ -514,5 +512,5 @@ under "/content/polls/", or any 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 :ref:`part 4 of this tutorial
-<intro-tutorial04>` to learn about simple form processing and generic views.
+When you're comfortable with writing views, read :doc:`part 4 of this tutorial
+</intro/tutorial04>` to learn about simple form processing and generic views.
22 docs/intro/tutorial04.txt
View
@@ -1,10 +1,8 @@
-.. _intro-tutorial04:
-
=====================================
Writing your first Django app, part 4
=====================================
-This tutorial begins where :ref:`Tutorial 3 <intro-tutorial03>` left off. We're
+This tutorial begins where :doc:`Tutorial 3 </intro/tutorial03>` left off. We're
continuing the Web-poll application and will focus on simple form processing and
cutting down our code.
@@ -70,7 +68,7 @@ The details of how this works are explained in the documentation for
:ref:`RequestContext <subclassing-context-requestcontext>`.
Now, let's create a Django view that handles the submitted data and does
-something with it. Remember, in :ref:`Tutorial 3 <intro-tutorial03>`, we
+something with it. Remember, in :doc:`Tutorial 3 </intro/tutorial03>`, we
created a URLconf for the polls application that includes this line::
(r'^(?P<poll_id>\d+)/vote/$', 'vote'),
@@ -149,7 +147,7 @@ This code includes a few things we haven't covered yet in this tutorial:
As mentioned in Tutorial 3, ``request`` is a :class:`~django.http.HttpRequest`
object. For more on :class:`~django.http.HttpRequest` objects, see the
-:ref:`request and response documentation <ref-request-response>`.
+:doc:`request and response documentation </ref/request-response>`.
After somebody votes in a poll, the ``vote()`` view redirects to the results
page for the poll. Let's write that view::
@@ -158,8 +156,8 @@ 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 :ref:`Tutorial 3
-<intro-tutorial03>`. The only difference is the template name. We'll fix this
+This is almost exactly the same as the ``detail()`` view from :doc:`Tutorial 3
+</intro/tutorial03>`. The only difference is the template name. We'll fix this
redundancy later.
Now, create a ``results.html`` template:
@@ -183,7 +181,7 @@ without having chosen a choice, you should see the error message.
Use generic views: Less code is better
======================================
-The ``detail()`` (from :ref:`Tutorial 3 <intro-tutorial03>`) and ``results()``
+The ``detail()`` (from :doc:`Tutorial 3 </intro/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.
@@ -328,8 +326,8 @@ are) used multiple times -- but we can use the name we've given::
Run the server, and use your new polling app based on generic views.
-For full details on generic views, see the :ref:`generic views documentation
-<topics-http-generic-views>`.
+For full details on generic views, see the :doc:`generic views documentation
+</topics/http/generic-views>`.
Coming soon
===========
@@ -344,5 +342,5 @@ will cover:
* Advanced admin features: Permissions
* Advanced admin features: Custom JavaScript
-In the meantime, you might want to check out some pointers on :ref:`where to go
-from here <intro-whatsnext>`
+In the meantime, you might want to check out some pointers on :doc:`where to go
+from here </intro/whatsnext>`
34 docs/intro/whatsnext.txt
View
@@ -1,10 +1,8 @@
-.. _intro-whatsnext:
-
=================
What to read next
=================
-So you've read all the :ref:`introductory material <intro-index>` and have
+So you've read all the :doc:`introductory material </intro/index>` and have
decided you'd like to keep using Django. We've only just scratched the surface
with this intro (in fact, if you've read every single word you've still read
less than 10% of the overall documentation).
@@ -37,15 +35,15 @@ How the documentation is organized
Django's main documentation is broken up into "chunks" designed to fill
different needs:
- * The :ref:`introductory material <intro-index>` is designed for people new
+ * The :doc:`introductory material </intro/index>` is designed for people new
to Django -- or to web development in general. It doesn't cover anything
in depth, but instead gives a high-level overview of how developing in
Django "feels".
- * The :ref:`topic guides <topics-index>`, on the other hand, dive deep into
+ * The :doc:`topic guides </topics/index>`, on the other hand, dive deep into
individual parts of Django. There are complete guides to Django's
- :ref:`model system <topics-db-index>`, :ref:`template engine
- <topics-templates>`, :ref:`forms framework <topics-forms-index>`, and much
+ :doc:`model system </topics/db/index>`, :doc:`template engine
+ </topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much
more.
This is probably where you'll want to spend most of your time; if you work
@@ -53,27 +51,27 @@ different needs:
everything there is to know about Django.
* Web development is often broad, not deep -- problems span many domains.
- We've written a set of :ref:`how-to guides <howto-index>` that answer
+ We've written a set of :doc:`how-to guides </howto/index>` that answer
common "How do I ...?" questions. Here you'll find information about
- :ref:`generating PDFs with Django <howto-outputting-pdf>`, :ref:`writing
- custom template tags <howto-custom-template-tags>`, and more.
+ :doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing
+ custom template tags </howto/custom-template-tags>`, and more.
- Answers to really common questions can also be found in the :ref:`FAQ
- <faq-index>`.
+ Answers to really common questions can also be found in the :doc:`FAQ
+ </faq/index>`.
* The guides and how-to's don't cover every single class, function, and
method available in Django -- that would be overwhelming when you're
trying to learn. Instead, details about individual classes, functions,
- methods, and modules are kept in the :ref:`reference <ref-index>`. This is
+ methods, and modules are kept in the :doc:`reference </ref/index>`. This is
where you'll turn to find the details of a particular function or
whathaveyou.
* Finally, there's some "specialized" documentation not usually relevant to
- most developers. This includes the :ref:`release notes <releases-index>`,
- :ref:`documentation of obsolete features <obsolete-index>`,
- :ref:`internals documentation <internals-index>` for those who want to add
- code to Django itself, and a :ref:`few other things that simply don't fit
- elsewhere <misc-index>`.
+ most developers. This includes the :doc:`release notes </releases/index>`,
+ :doc:`documentation of obsolete features </obsolete/index>`,
+ :doc:`internals documentation </internals/index>` for those who want to add
+ code to Django itself, and a :doc:`few other things that simply don't fit
+ elsewhere </misc/index>`.
How documentation is updated
58 docs/misc/api-stability.txt
View
@@ -1,10 +1,8 @@
-.. _misc-api-stability:
-
=============
API stability
=============
-:ref:`The release of Django 1.0 <releases-1.0>` comes with a promise of API
+:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API
stability and forwards-compatibility. In a nutshell, this means that code you
develop against Django 1.0 will continue to work against 1.1 unchanged, and you
should need to make only minor changes for any 1.X release.
@@ -37,67 +35,67 @@ Stable APIs
===========
In general, everything covered in the documentation -- with the exception of
-anything in the :ref:`internals area <internals-index>` is considered stable as
+anything in the :doc:`internals area </internals/index>` is considered stable as
of 1.0. This includes these APIs:
- - :ref:`Authorization <topics-auth>`
+ - :doc:`Authorization </topics/auth>`
- - :ref:`Caching <topics-cache>`.
+ - :doc:`Caching </topics/cache>`.
- - :ref:`Model definition, managers, querying and transactions
- <topics-db-index>`
+ - :doc:`Model definition, managers, querying and transactions
+ </topics/db/index>`
- - :ref:`Sending e-mail <topics-email>`.
+ - :doc:`Sending e-mail </topics/email>`.
- - :ref:`File handling and storage <topics-files>`
+ - :doc:`File handling and storage </topics/files>`
- - :ref:`Forms <topics-forms-index>`
+ - :doc:`Forms </topics/forms/index>`
- - :ref:`HTTP request/response handling <topics-http-index>`, including file
+ - :doc:`HTTP request/response handling </topics/http/index>`, including file
uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
- - :ref:`Generic views <topics-http-generic-views>`.
+ - :doc:`Generic views </topics/http/generic-views>`.
- - :ref:`Internationalization <topics-i18n>`.
+ - :doc:`Internationalization </topics/i18n/index>`.
- - :ref:`Pagination <topics-pagination>`
+ - :doc:`Pagination </topics/pagination>`
- - :ref:`Serialization <topics-serialization>`
+ - :doc:`Serialization </topics/serialization>`
- - :ref:`Signals <topics-signals>`
+ - :doc:`Signals </topics/signals>`
- - :ref:`Templates <topics-templates>`, including the language, Python-level
- :ref:`template APIs <ref-templates-index>`, and :ref:`custom template tags
- and libraries <howto-custom-template-tags>`. We may add new template
+ - :doc:`Templates </topics/templates>`, including the language, Python-level
+ :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags
+ and libraries </howto/custom-template-tags>`. We may add new template
tags in the future and the names may inadvertently clash with
external template tags. Before adding any such tags, we'll ensure that
Django raises an error if it tries to load tags with duplicate names.
- - :ref:`Testing <topics-testing>`
+ - :doc:`Testing </topics/testing>`
- - :ref:`django-admin utility <ref-django-admin>`.
+ - :doc:`django-admin utility </ref/django-admin>`.
- - :ref:`Built-in middleware <ref-middleware>`
+ - :doc:`Built-in middleware </ref/middleware>`
- - :ref:`Request/response objects <ref-request-response>`.
+ - :doc:`Request/response objects </ref/request-response>`.
- - :ref:`Settings <ref-settings>`. Note, though that while the :ref:`list of
- built-in settings <ref-settings>` can be considered complete we may -- and
+ - :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of
+ built-in settings </ref/settings>` can be considered complete we may -- and
probably will -- add new settings in future versions. This is one of those
places where "'stable' does not mean 'complete.'"
- - :ref:`Built-in signals <ref-signals>`. Like settings, we'll probably add
+ - :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add
new signals in the future, but the existing ones won't break.
- - :ref:`Unicode handling <ref-unicode>`.
+ - :doc:`Unicode handling </ref/unicode>`.
- - Everything covered by the :ref:`HOWTO guides <howto-index>`.
+ - Everything covered by the :doc:`HOWTO guides </howto/index>`.
``django.utils``
----------------
Most of the modules in ``django.utils`` are designed for internal use. Only
-the following parts of :ref:`django.utils <ref-utils>` can be considered stable:
+the following parts of :doc:`django.utils </ref/utils>` can be considered stable:
- ``django.utils.cache``
- ``django.utils.datastructures.SortedDict`` -- only this single class; the
2  docs/misc/design-philosophies.txt
View
@@ -1,5 +1,3 @@
-.. _misc-design-philosophies:
-
===================
Design philosophies
===================
2  docs/misc/distributions.txt
View
@@ -1,5 +1,3 @@
-.. _misc-distributions:
-
===================================
Third-party distributions of Django
===================================
2  docs/misc/index.txt
View
@@ -1,5 +1,3 @@
-.. _misc-index:
-
Meta-documentation and miscellany
=================================
2  docs/obsolete/admin-css.txt
View
@@ -1,5 +1,3 @@
-.. _obsolete-admin-css:
-
======================================