diff options
Diffstat (limited to 'docs/ref/contrib')
42 files changed, 713 insertions, 663 deletions
diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index 62f944d9b6..86a5355b28 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/docs/ref/contrib/admin/actions.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-admin-actions: - ============= Admin actions ============= @@ -208,7 +206,7 @@ objects. To provide an intermediary page, simply return an :class:`~django.http.HttpResponse` (or subclass) from your action. For example, you might write a simple export function that uses Django's -:ref:`serialization functions <topics-serialization>` to dump some selected +:doc:`serialization functions </topics/serialization>` to dump some selected objects as JSON:: from django.http import HttpResponse @@ -294,7 +292,7 @@ Disabling a site-wide action site-wide. If, however, you need to re-enable a globally-disabled action for one - particular model, simply list it explicitally in your ``ModelAdmin.actions`` + particular model, simply list it explicitly in your ``ModelAdmin.actions`` list:: # Globally disable delete selected diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 7fee903715..055057677c 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-admin: - ===================== The Django admin site ===================== @@ -7,8 +5,6 @@ The Django admin site .. module:: django.contrib.admin :synopsis: Django's admin site. -.. currentmodule:: django.contrib.admin - One of the most powerful parts of Django is the automatic admin interface. It reads metadata in your model to provide a powerful and production-ready interface that content producers can immediately use to start adding content to @@ -474,17 +470,16 @@ change list page. By default, this is set to ``100``. .. attribute:: ModelAdmin.list_select_related -Set ``list_select_related`` to tell Django to use ``select_related()`` in -retrieving the list of objects on the admin change list page. This can save you -a bunch of database queries. +Set ``list_select_related`` to tell Django to use +:meth:`~django.db.models.QuerySet.select_related` in retrieving the list of +objects on the admin change list page. This can save you a bunch of database +queries. 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 -:ref:`the select_related() docs <select-related>`. +Note that Django will use :meth:`~django.db.models.QuerySet.select_related`, +regardless of this setting, if one of the ``list_display`` fields is a +``ForeignKey``. .. attribute:: ModelAdmin.inlines @@ -595,11 +590,16 @@ This should be set to a list of field names that will be searched whenever somebody submits a search query in that text box. These fields should be some kind of text field, such as ``CharField`` or -``TextField``. You can also perform a related lookup on a ``ForeignKey`` with -the lookup API "follow" notation:: +``TextField``. You can also perform a related lookup on a ``ForeignKey`` or +``ManyToManyField`` with the lookup API "follow" notation:: search_fields = ['foreign_key__related_fieldname'] +For example, if you have a blog entry with an author, the following definition +would enable search blog entries by the email address of the author:: + + search_fields = ['user__email'] + When somebody does a search in the admin search box, Django splits the search query into words and returns all objects that contain each of the words, case insensitive, where each word must be in at least one of ``search_fields``. For @@ -674,7 +674,7 @@ do that:: Note that the key in the dictionary is the actual field class, *not* a string. The value is another dictionary; these arguments will be passed to -:meth:`~django.forms.Field.__init__`. See :ref:`ref-forms-api` for details. +:meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for details. .. warning:: @@ -692,7 +692,7 @@ The value is another dictionary; these arguments will be passed to .. versionadded:: 1.1 A list of actions to make available on the change list page. See -:ref:`ref-contrib-admin-actions` for details. +:doc:`/ref/contrib/admin/actions` for details. .. attribute:: ModelAdmin.actions_on_top .. attribute:: ModelAdmin.actions_on_bottom @@ -743,8 +743,8 @@ templates used by the :class:`ModelAdmin` views: Path to a custom template, used by the :meth:`delete_selected` action method for displaying a confirmation page when deleting one - or more objects. See the :ref:`actions - documentation<ref-contrib-admin-actions>`. + or more objects. See the :doc:`actions + documentation</ref/contrib/admin/actions>`. .. attribute:: ModelAdmin.object_history_template @@ -801,7 +801,7 @@ described above in the :attr:`ModelAdmin.readonly_fields` section. The ``get_urls`` method on a ``ModelAdmin`` returns the URLs to be used for that ModelAdmin in the same way as a URLconf. Therefore you can extend them as -documented in :ref:`topics-http-urls`:: +documented in :doc:`/topics/http/urls`:: class MyModelAdmin(admin.ModelAdmin): def get_urls(self): @@ -829,7 +829,7 @@ problems: Since this is usually not what you want, Django provides a convenience wrapper to check permissions and mark the view as non-cacheable. This wrapper is -:meth:`AdminSite.admin_view` (i.e. ``self.admin_site.admin_view`` inside a +:meth:`AdminSite.admin_view` (i.e. ``self.admin_site.admin_view`` inside a ``ModelAdmin`` instance); use it like so:: class MyModelAdmin(admin.ModelAdmin): @@ -865,11 +865,26 @@ return a subset of objects for this foreign key field based on the user:: def formfield_for_foreignkey(self, db_field, request, **kwargs): if db_field.name == "car": kwargs["queryset"] = Car.objects.filter(owner=request.user) - return db_field.formfield(**kwargs) return super(MyModelAdmin, self).formfield_for_foreignkey(db_field, request, **kwargs) This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key field -to only the cars owned by the ``User`` instance. +to only display the cars owned by the ``User`` instance. + +.. method:: ModelAdmin.formfield_for_manytomany(self, db_field, request, **kwargs) + +.. versionadded:: 1.1 + +Like the ``formfield_for_foreignkey`` method, the ``formfield_for_manytomany`` +method can be overridden to change the default formfield for a many to many +field. For example, if an owner can own multiple cars and cars can belong +to multiple owners -- a many to many relationship -- you could filter the +``Car`` foreign key field to only display the cars owned by the ``User``:: + + class MyModelAdmin(admin.ModelAdmin): + def formfield_for_manytomany(self, db_field, request, **kwargs): + if db_field.name == "cars": + kwargs["queryset"] = Car.objects.filter(owner=request.user) + return super(MyModelAdmin, self).formfield_for_manytomany(db_field, request, **kwargs) .. method:: ModelAdmin.queryset(self, request) @@ -950,7 +965,7 @@ on your ``ModelAdmin``:: js = ("my_code.js",) Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules -apply as :ref:`regular media definitions on forms <topics-forms-media>`. +apply as :doc:`regular media definitions on forms </topics/forms/media>`. Django admin Javascript makes use of the `jQuery`_ library. To avoid conflict with user scripts, Django's jQuery is namespaced as @@ -983,8 +998,8 @@ any field:: return self.cleaned_data["name"] It is important you use a ``ModelForm`` here otherwise things can break. See the -:ref:`forms <ref-forms-index>` documentation on :ref:`custom validation -<ref-forms-validation>` and, more specifically, the +:doc:`forms </ref/forms/index>` documentation on :doc:`custom validation +</ref/forms/validation>` and, more specifically, the :ref:`model form validation notes <overriding-modelform-clean-method>` for more information. @@ -993,6 +1008,8 @@ information. ``InlineModelAdmin`` objects ============================ +.. class:: InlineModelAdmin + The admin interface has the ability to edit models on the same page as a parent model. These are called inlines. Suppose you have these two models:: @@ -1027,90 +1044,88 @@ The difference between these two is merely the template used to render them. The ``InlineModelAdmin`` class is a subclass of ``ModelAdmin`` so it inherits all the same functionality as well as some of its own: -``model`` -~~~~~~~~~ +.. attribute:: InlineModelAdmin.model -The model in which the inline is using. This is required. + The model in which the inline is using. This is required. -``fk_name`` -~~~~~~~~~~~ +.. attribute:: InlineModelAdmin.fk_name -The name of the foreign key on the model. In most cases this will be dealt -with automatically, but ``fk_name`` must be specified explicitly if there are -more than one foreign key to the same parent model. + The name of the foreign key on the model. In most cases this will be dealt + with automatically, but ``fk_name`` must be specified explicitly if there + are more than one foreign key to the same parent model. -``formset`` -~~~~~~~~~~~ +.. attribute:: InlineModelAdmin.formset -This defaults to ``BaseInlineFormSet``. Using your own formset can give you -many possibilities of customization. Inlines are built around -:ref:`model formsets <model-formsets>`. + This defaults to ``BaseInlineFormSet``. Using your own formset can give you + many possibilities of customization. Inlines are built around + :ref:`model formsets <model-formsets>`. -``form`` -~~~~~~~~ +.. attribute:: InlineModelAdmin.form -The value for ``form`` defaults to ``ModelForm``. This is what is -passed through to ``inlineformset_factory`` when creating the formset for this -inline. + The value for ``form`` defaults to ``ModelForm``. This is what is passed + through to ``inlineformset_factory`` when creating the formset for this + inline. .. _ref-contrib-admin-inline-extra: -``extra`` -~~~~~~~~~ +.. attribute:: InlineModelAdmin.extra -This controls the number of extra forms the formset will display in addition -to the initial forms. See the -:ref:`formsets documentation <topics-forms-formsets>` for more information. -.. versionadded:: 1.2 + This controls the number of extra forms the formset will display in addition + to the initial forms. See the + :doc:`formsets documentation </topics/forms/formsets>` for more information. -For users with JavaScript-enabled browsers, an "Add another" link is -provided to enable any number of additional inlines to be added in -addition to those provided as a result of the ``extra`` argument. + .. versionadded:: 1.2 -The dynamic link will not appear if the number of currently displayed -forms exceeds ``max_num``, or if the user does not have JavaScript -enabled. + For users with JavaScript-enabled browsers, an "Add another" link is + provided to enable any number of additional inlines to be added in addition + to those provided as a result of the ``extra`` argument. + + The dynamic link will not appear if the number of currently displayed forms + exceeds ``max_num``, or if the user does not have JavaScript enabled. .. _ref-contrib-admin-inline-max-num: -``max_num`` -~~~~~~~~~~~ +.. attribute:: InlineModelAdmin.max_num -This controls the maximum number of forms to show in the inline. This doesn't -directly correlate to the number of objects, but can if the value is small -enough. See :ref:`model-formsets-max-num` for more information. + This controls the maximum number of forms to show in the inline. This + doesn't directly correlate to the number of objects, but can if the value + is small enough. See :ref:`model-formsets-max-num` for more information. -``raw_id_fields`` -~~~~~~~~~~~~~~~~~ +.. attribute:: InlineModelAdmin.raw_id_fields -By default, Django's admin uses a select-box interface (<select>) for -fields that are ``ForeignKey``. Sometimes you don't want to incur the -overhead of having to select all the related instances to display in the -drop-down. + By default, Django's admin uses a select-box interface (<select>) for + fields that are ``ForeignKey``. Sometimes you don't want to incur the + overhead of having to select all the related instances to display in the + drop-down. -``raw_id_fields`` is a list of fields you would like to change -into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``:: + ``raw_id_fields`` is a list of fields you would like to change into a + ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``:: - class BookInline(admin.TabularInline): - model = Book - raw_id_fields = ("pages",) + class BookInline(admin.TabularInline): + model = Book + raw_id_fields = ("pages",) -``template`` -~~~~~~~~~~~~ -The template used to render the inline on the page. +.. attribute:: InlineModelAdmin.template -``verbose_name`` -~~~~~~~~~~~~~~~~ + The template used to render the inline on the page. -An override to the ``verbose_name`` found in the model's inner ``Meta`` class. +.. attribute:: InlineModelAdmin.verbose_name -``verbose_name_plural`` -~~~~~~~~~~~~~~~~~~~~~~~ + An override to the ``verbose_name`` found in the model's inner ``Meta`` + class. + +.. attribute:: InlineModelAdmin.verbose_name_plural + + An override to the ``verbose_name_plural`` found in the model's inner + ``Meta`` class. + +.. attribute:: InlineModelAdmin.can_delete + + Specifies whether or not inline objects can be deleted in the inline. + Defaults to ``True``. -An override to the ``verbose_name_plural`` found in the model's inner ``Meta`` -class. Working with a model with two or more foreign keys to the same parent model --------------------------------------------------------------------------- @@ -1189,7 +1204,7 @@ your admin page for managing the relation. In all other respects, the ``InlineModelAdmin`` is exactly the same as any other. You can customize the appearance using any of the normal -``InlineModelAdmin`` properties. +``ModelAdmin`` properties. Working with Many-to-Many Intermediary Models ---------------------------------------------- @@ -1281,7 +1296,7 @@ example app:: ``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline`` and ``GenericStackedInline`` and behave just like any other inline. See the -:ref:`contenttypes documentation <ref-contrib-contenttypes>` for more specific +:doc:`contenttypes documentation </ref/contrib/contenttypes>` for more specific information. Overriding Admin Templates diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index 03f5ff1281..619b38e5ac 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -1,6 +1,4 @@ -.. _ref-contrib-auth: - ``django.contrib.auth`` ======================= -See :ref:`topics-auth`. +See :doc:`/topics/auth`. diff --git a/docs/ref/contrib/comments/custom.txt b/docs/ref/contrib/comments/custom.txt index 9e32fc4fed..49299d4d33 100644 --- a/docs/ref/contrib/comments/custom.txt +++ b/docs/ref/contrib/comments/custom.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-custom: - ================================== Customizing the comments framework ================================== diff --git a/docs/ref/contrib/comments/example.txt b/docs/ref/contrib/comments/example.txt index d4ce623bb0..424bdb13f5 100644 --- a/docs/ref/contrib/comments/example.txt +++ b/docs/ref/contrib/comments/example.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-example: - .. highlightlang:: html+django =========================================== @@ -7,7 +5,7 @@ Example of using the in-built comments app =========================================== Follow the first three steps of the quick start guide in the -:ref:`documentation <ref-contrib-comments-index>`. +:doc:`documentation </ref/contrib/comments/index>`. Now suppose, you have an app (``blog``) with a model (``Post``) to which you want to attach comments. Let us also suppose that @@ -85,8 +83,8 @@ It looks for the ``form.html`` under the following directories Since we customize the form in the second method, we make use of another tag called :ttag:`comment_form_target`. This tag on rendering gives the URL -where the comment form is posted. Without any :ref:`customization -<ref-contrib-comments-custom>`, :ttag:`comment_form_target` evaluates to +where the comment form is posted. Without any :doc:`customization +</ref/contrib/comments/custom>`, :ttag:`comment_form_target` evaluates to ``/comments/post/``. We use this tag in the form's ``action`` attribute. The :ttag:`get_comment_form` tag renders a ``form`` for a model instance by @@ -136,7 +134,7 @@ found under the directory structure we saw for ``form.html``. Feeds ===== -Suppose you want to export a :ref:`feed <ref-contrib-syndication>` of the +Suppose you want to export a :doc:`feed </ref/contrib/syndication>` of the latest comments, you can use the in-built :class:`LatestCommentFeed`. Just enable it in your project's ``urls.py``: @@ -163,8 +161,8 @@ Moderation Now that we have the comments framework working, we might want to have some moderation setup to administer the comments. The comments framework comes -in-built with :ref:`generic comment moderation -<ref-contrib-comments-moderation>`. The comment moderation has the following +in-built with :doc:`generic comment moderation +</ref/contrib/comments/moderation>`. The comment moderation has the following features (all of which or only certain can be enabled): * Enable comments for a particular model instance. @@ -181,18 +179,18 @@ following way: from django.contrib.comments.moderation import CommentModerator, moderator from django.db import models - + class Post(models.Model): title = models.CharField(max_length = 255) content = models.TextField() posted_date = models.DateTimeField() - + class PostModerator(CommentModerator): email_notification = True auto_close_field = 'posted_date' # Close the comments after 7 days. close_after = 7 - + moderator.register(Post, PostModerator) The generic comment moderation also has the facility to remove comments. diff --git a/docs/ref/contrib/comments/forms.txt b/docs/ref/contrib/comments/forms.txt index 3eacb5db54..c21a27bb9e 100644 --- a/docs/ref/contrib/comments/forms.txt +++ b/docs/ref/contrib/comments/forms.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-forms: - ==================== Comment form classes ==================== @@ -9,7 +7,7 @@ Comment form classes The ``django.contrib.comments.forms`` module contains a handful of forms you'll use when writing custom views dealing with comments, or when writing -:ref:`custom comment apps <ref-contrib-comments-custom>`. +:doc:`custom comment apps </ref/contrib/comments/custom>`. .. class:: CommentForm @@ -23,7 +21,7 @@ you'll use when writing custom views dealing with comments, or when writing Abstract comment forms for custom comment apps ---------------------------------------------- -If you're building a :ref:`custom comment app <ref-contrib-comments-custom>`, +If you're building a :doc:`custom comment app </ref/contrib/comments/custom>`, you might want to replace *some* of the form logic but still rely on parts of the existing form. diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 9f1d3cd6e4..817871e976 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/docs/ref/contrib/comments/index.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-index: - =========================== Django's comments framework =========================== @@ -16,7 +14,7 @@ it for comments on blog entries, photos, book chapters, or anything else. .. note:: If you used to use Django's older (undocumented) comments framework, you'll - need to upgrade. See the :ref:`upgrade guide <ref-contrib-comments-upgrade>` + need to upgrade. See the :doc:`upgrade guide </ref/contrib/comments/upgrade>` for instructions. Quick start guide @@ -42,7 +40,7 @@ To get started using the ``comments`` app, follow these steps: #. Use the `comment template tags`_ below to embed comments in your templates. -You might also want to examine :ref:`ref-contrib-comments-settings`. +You might also want to examine :doc:`/ref/contrib/comments/settings`. Comment template tags ===================== @@ -124,7 +122,7 @@ For example:: {% endfor %} This returns a list of :class:`~django.contrib.comments.models.Comment` objects; -see :ref:`the comment model documentation <ref-contrib-comments-models>` for +see :doc:`the comment model documentation </ref/contrib/comments/models>` for details. .. templatetag:: get_comment_permalink @@ -212,7 +210,7 @@ Rendering a custom comment form ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want more control over the look and feel of the comment form, you use use -:ttag:`get_comment_form` to get a :ref:`form object <topics-forms-index>` that +:ttag:`get_comment_form` to get a :doc:`form object </topics/forms/index>` that you can use in the template:: {% get_comment_form for [object] as [varname] %} @@ -279,8 +277,8 @@ should know about: it with a warning field; if you use the comment form with a custom template you should be sure to do the same. -The comments app also depends on the more general :ref:`Cross Site Request -Forgery protection < ref-contrib-csrf>` that comes with Django. As described in +The comments app also depends on the more general :doc:`Cross Site Request +Forgery protection </ref/contrib/csrf>` that comes with Django. As described in the documentation, it is best to use ``CsrfViewMiddleware``. However, if you are not using that, you will need to use the ``csrf_protect`` decorator on any views that include the comment form, in order for those views to be able to diff --git a/docs/ref/contrib/comments/models.txt b/docs/ref/contrib/comments/models.txt index af85d68f00..e773790d65 100644 --- a/docs/ref/contrib/comments/models.txt +++ b/docs/ref/contrib/comments/models.txt @@ -1,82 +1,80 @@ -.. _ref-contrib-comments-models: - =========================== The built-in comment models =========================== .. module:: django.contrib.comments.models :synopsis: The built-in comment models - + .. class:: Comment Django's built-in comment model. Has the following fields: - + .. attribute:: content_object - + A :class:`~django.contrib.contettypes.generic.GenericForeignKey` attribute pointing to the object the comment is attached to. You can use this to get at the related object (i.e. ``my_comment.content_object``). - + Since this field is a :class:`~django.contrib.contettypes.generic.GenericForeignKey`, it's actually syntactic sugar on top of two underlying attributes, described below. - + .. attribute:: content_type - + A :class:`~django.db.models.ForeignKey` to :class:`~django.contrib.contenttypes.models.ContentType`; this is the type of the object the comment is attached to. - + .. attribute:: object_pk - + A :class:`~django.db.models.TextField` containing the primary key of the object the comment is attached to. - + .. attribute:: site - + A :class:`~django.db.models.ForeignKey` to the :class:`~django.contrib.sites.models.Site` on which the comment was posted. - + .. attribute:: user - + A :class:`~django.db.models.ForeignKey` to the :class:`~django.contrib.auth.models.User` who posted the comment. May be blank if the comment was posted by an unauthenticated user. - + .. attribute:: user_name - + The name of the user who posted the comment. - + .. attribute:: user_email - - The email of the user who posteed the comment. - + + The email of the user who posted the comment. + .. attribute:: user_url - + The URL entered by the person who posted the comment. - + .. attribute:: comment - + The actual content of the comment itself. - + .. attribute:: submit_date - + The date the comment was submitted. - + .. attribute:: ip_address - + The IP address of the user posting the comment. - + .. attribute:: is_public - + ``False`` if the comment is in moderation (see - :ref:`ref-contrib-comments-moderation`); If ``True``, the comment will + :doc:`/ref/contrib/comments/moderation`); If ``True``, the comment will be displayed on the site. - + .. attribute:: is_removed - + ``True`` if the comment was removed. Used to keep track of removed comments instead of just deleting them. - + diff --git a/docs/ref/contrib/comments/moderation.txt b/docs/ref/contrib/comments/moderation.txt index 2c4072ba5b..198f78fa89 100644 --- a/docs/ref/contrib/comments/moderation.txt +++ b/docs/ref/contrib/comments/moderation.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-moderation: - ========================== Generic comment moderation ========================== diff --git a/docs/ref/contrib/comments/settings.txt b/docs/ref/contrib/comments/settings.txt index ff94d2dbcc..1f1aecafd4 100644 --- a/docs/ref/contrib/comments/settings.txt +++ b/docs/ref/contrib/comments/settings.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-settings: - ================ Comment settings ================ @@ -29,7 +27,7 @@ this will be rejected. Defaults to 3000. COMMENTS_APP ------------ -An app which provides :ref:`customization of the comments framework -<ref-contrib-comments-custom>`. Use the same dotted-string notation +An app which provides :doc:`customization of the comments framework +</ref/contrib/comments/custom>`. Use the same dotted-string notation as in :setting:`INSTALLED_APPS`. Your custom :setting:`COMMENTS_APP` must also be listed in :setting:`INSTALLED_APPS`. diff --git a/docs/ref/contrib/comments/signals.txt b/docs/ref/contrib/comments/signals.txt index cd406b56dd..7ae34a1900 100644 --- a/docs/ref/contrib/comments/signals.txt +++ b/docs/ref/contrib/comments/signals.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-signals: - ================================ Signals sent by the comments app ================================ @@ -7,9 +5,9 @@ Signals sent by the comments app .. module:: django.contrib.comments.signals :synopsis: Signals sent by the comment module. -The comment app sends a series of :ref:`signals <topics-signals>` to allow for -comment moderation and similar activities. See :ref:`the introduction to signals -<topics-signals>` for information about how to register for and receive these +The comment app sends a series of :doc:`signals </topics/signals>` to allow for +comment moderation and similar activities. See :doc:`the introduction to signals +</topics/signals>` for information about how to register for and receive these signals. comment_will_be_posted diff --git a/docs/ref/contrib/comments/upgrade.txt b/docs/ref/contrib/comments/upgrade.txt index dc9bff868c..3d6b5af668 100644 --- a/docs/ref/contrib/comments/upgrade.txt +++ b/docs/ref/contrib/comments/upgrade.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-comments-upgrade: - =============================================== Upgrading from Django's previous comment system =============================================== @@ -11,8 +9,8 @@ The main changes from the old system are: * This new system is documented. - * It uses modern Django features like :ref:`forms <topics-forms-index>` and - :ref:`modelforms <topics-forms-modelforms>`. + * It uses modern Django features like :doc:`forms </topics/forms/index>` and + :doc:`modelforms </topics/forms/modelforms>`. * It has a single ``Comment`` model instead of separate ``FreeComment`` and ``Comment`` models. @@ -42,7 +40,7 @@ The data models for Django's comment system have changed, as have the table names. Before you transfer your existing data into the new comments system, make sure that you have installed the new comments system as explained in the -:ref:`quick start guide <ref-contrib-comments-index>`. +:doc:`quick start guide </ref/contrib/comments/index>`. This will ensure that the new tables have been properly created. To transfer your data into the new comments system, you'll need to directly diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 3085bf3ee9..b6956512ad 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-contenttypes: - ========================== The contenttypes framework ========================== @@ -114,7 +112,7 @@ Methods on ``ContentType`` instances Takes a set of valid :ref:`lookup arguments <field-lookups-intro>` for the model the :class:`~django.contrib.contenttypes.models.ContentType` - represents, and does :ref:`a get() lookup <get-kwargs>` on that model, + represents, and does :lookup:`a get() lookup <get>` on that model, returning the corresponding object. .. method:: models.ContentType.model_class() @@ -324,15 +322,19 @@ same types of lookups manually:: ... object_id=b.id) [<TaggedItem: django>, <TaggedItem: python>] -Note that if the model with a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` -that you're referring to uses a non-default value for ``ct_field`` or ``fk_field`` -(e.g. the :mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), -you'll need to pass ``content_type_field`` and ``object_id_field`` to -:class:`~django.contrib.contenttypes.generic.GenericRelation`.:: +Note that if the model in a +:class:`~django.contrib.contenttypes.generic.GenericRelation` uses a +non-default value for ``ct_field`` or ``fk_field`` in its +:class:`~django.contrib.contenttypes.generic.GenericForeignKey` (e.g. the +:mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), +you'll need to set ``content_type_field`` and/or ``object_id_field`` in +the :class:`~django.contrib.contenttypes.generic.GenericRelation` to +match the ``ct_field`` and ``fk_field``, respectively, in the +:class:`~django.contrib.contenttypes.generic.GenericForeignKey`:: - comments = generic.GenericRelation(Comment, content_type_field="content_type", object_id_field="object_pk") + comments = generic.GenericRelation(Comment, object_id_field="object_pk") -Note that if you delete an object that has a +Note also, that if you delete an object that has a :class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects which have a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` pointing at it will be deleted as well. In the example above, this means that @@ -342,7 +344,7 @@ it would be deleted at the same time. Generic relations and aggregation --------------------------------- -:ref:`Django's database aggregation API <topics-db-aggregation>` +:doc:`Django's database aggregation API </topics/db/aggregation>` doesn't work with a :class:`~django.contrib.contenttypes.generic.GenericRelation`. For example, you might be tempted to try something like:: @@ -361,14 +363,14 @@ Generic relations in forms and admin :class:`~django.contrib.contenttypes.generic.GenericInlineFormSet` and :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`. This enables the use of generic relations in forms and the admin. See the -:ref:`model formset <topics-forms-modelforms>` and -:ref:`admin <ref-contrib-admin>` documentation for more information. +:doc:`model formset </topics/forms/modelforms>` and +:doc:`admin </ref/contrib/admin/index>` documentation for more information. .. class:: generic.GenericInlineModelAdmin The :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin` class inherits all properties from an - :class:`~django.contrib.admin.options.InlineModelAdmin` class. However, + :class:`~django.contrib.admin.InlineModelAdmin` class. However, it adds a couple of its own for working with the generic relation: .. attribute:: generic.GenericInlineModelAdmin.ct_field diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt index d8a944b10a..c32dd73986 100644 --- a/docs/ref/contrib/csrf.txt +++ b/docs/ref/contrib/csrf.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-csrf: - ===================================== Cross Site Request Forgery protection ===================================== @@ -400,6 +398,13 @@ set a flag on requests which relaxes the middleware and the ``csrf_protect`` decorator so that they no longer rejects requests. In every other respect (e.g. sending cookies etc.), they behave the same. +If, for some reason, you *want* the test client to perform CSRF +checks, you can create an instance of the test client that enforces +CSRF checks:: + + >>> from django.test import Client + >>> csrf_client = Client(enforce_csrf_checks=True) + Limitations =========== diff --git a/docs/ref/contrib/databrowse.txt b/docs/ref/contrib/databrowse.txt index d3536d150c..33c8228520 100644 --- a/docs/ref/contrib/databrowse.txt +++ b/docs/ref/contrib/databrowse.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-databrowse: - ========== Databrowse ========== @@ -49,8 +47,8 @@ How to use Databrowse Note that you should register the model *classes*, not instances. It doesn't matter where you put this, as long as it gets executed at some - point. A good place for it is in your :ref:`URLconf file - <topics-http-urls>` (``urls.py``). + point. A good place for it is in your :doc:`URLconf file + </topics/http/urls>` (``urls.py``). 3. Change your URLconf to import the :mod:`~django.contrib.databrowse` module:: @@ -73,20 +71,20 @@ code. Simply add the following import to your URLconf:: from django.contrib.auth.decorators import login_required -Then modify the :ref:`URLconf <topics-http-urls>` so that the +Then modify the :doc:`URLconf </topics/http/urls>` so that the :func:`databrowse.site.root` view is decorated with :func:`django.contrib.auth.decorators.login_required`:: (r'^databrowse/(.*)', login_required(databrowse.site.root)), -If you haven't already added support for user logins to your :ref:`URLconf -<topics-http-urls>`, as described in the :ref:`user authentication docs -<ref-contrib-auth>`, then you will need to do so now with the following +If you haven't already added support for user logins to your :doc:`URLconf +</topics/http/urls>`, as described in the :doc:`user authentication docs +</ref/contrib/auth>`, then you will need to do so now with the following mapping:: (r'^accounts/login/$', 'django.contrib.auth.views.login'), The final step is to create the login form required by :func:`django.contrib.auth.views.login`. The -:ref:`user authentication docs <ref-contrib-auth>` provide full details and a +:doc:`user authentication docs </ref/contrib/auth>` provide full details and a sample template that can be used for this purpose. diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 8c7f2781d0..ce6fdfcd1c 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-flatpages: - ================= The flatpages app ================= @@ -21,7 +19,7 @@ template. It can be associated with one, or multiple, sites. .. versionadded:: 1.0 -The content field may optionally be left blank if you prefer to put your +The content field may optionally be left blank if you prefer to put your content in a custom template. Here are some examples of flatpages on Django-powered sites: @@ -37,20 +35,20 @@ To install the flatpages app, follow these steps: 1. Install the :mod:`sites framework <django.contrib.sites>` by adding ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting, if it's not already in there. - + Also make sure you've correctly set :setting:`SITE_ID` to the ID of the site the settings file represents. This will usually be ``1`` (i.e. ``SITE_ID = 1``, but if you're using the sites framework to manage multiple sites, it could be the ID of a different site. - + 2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS` setting. - + 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'`` to your :setting:`MIDDLEWARE_CLASSES` setting. - + 4. Run the command :djadmin:`manage.py syncdb <syncdb>`. - + How it works ============ @@ -69,7 +67,7 @@ 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 :file:`flatpages/default.html`. - + * It passes that template a single context variable, :data:`flatpage`, which is the flatpage object. It uses :class:`~django.template.context.RequestContext` in rendering the @@ -92,11 +90,11 @@ Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at the end of the list, because it's a last resort. -For more on middleware, read the :ref:`middleware docs -<topics-http-middleware>`. +For more on middleware, read the :doc:`middleware docs +</topics/http/middleware>`. .. admonition:: Ensure that your 404 template works - + Note that the :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` only steps in once another view has successfully produced a 404 response. @@ -124,9 +122,9 @@ Via the Python API .. class:: models.FlatPage Flatpages are represented by a standard - :ref:`Django model <topics-db-models>`, + :doc:`Django model </topics/db/models>`, which lives in `django/contrib/flatpages/models.py`_. You can access - flatpage objects via the :ref:`Django database API <topics-db-queries>`. + flatpage objects via the :doc:`Django database API </topics/db/queries>`. .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py @@ -167,3 +165,64 @@ Since you're already entering raw HTML into the admin page for a flatpage, both ``flatpage.title`` and ``flatpage.content`` are marked as **not** requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the template. + +Getting a list of :class:`~django.contrib.flatpages.models.Flatpage` objects in your templates +============================================================================================== + +.. versionadded:: 1.3 + +The flatpages app provides a template tag that allows you to iterate +over all of the available flatpages on the :ref:`current site +<hooking-into-current-site-from-views>`. + +Like all custom template tags, you'll need to :ref:`load its custom +tag library <loading-custom-template-libraries>` before you can use +it. After loading the library, you can retrieve all current flatpages +via the :ttag:`get_flatpages` tag: + +.. code-block:: html+django + + {% load flatpages %} + {% get_flatpages as flatpages %} + <ul> + {% for page in flatpages %} + <li><a href="{{ page.url }}">{{ page.title }}</a></li> + {% endfor %} + </ul> + +.. templatetag:: get_flatpages + +Displaying ``registration_required`` flatpages +---------------------------------------------- + +By default, the :ttag:`get_flatpages` templatetag will only show +flatpages that are marked :attr:`registration_required`\=False. If you +want to display registration-protected flatpages, you need to specify +an authenticated user using a``for`` clause. + +For example: + +.. code-block:: html+django + + {% get_flatpages for someuser as about_pages %} + +If you provide an anonymous user, :ttag:`get_flatpages` will behave +the same as if you hadn't provided a user -- i.e., it will only show you +public flatpages. + +Limiting flatpages by base URL +------------------------------ + +An optional argument, ``starts_with``, can be applied to limit the +returned pages to those beginning with a particular base URL. This +argument may be passed as a string, or as a variable to be resolved +from the context. + +For example: + +.. code-block:: html+django + + {% get_flatpages '/about/' as about_pages %} + {% get_flatpages about_prefix as about_pages %} + {% get_flatpages '/about/' for someuser as about_pages %} + diff --git a/docs/ref/contrib/formtools/form-preview.txt b/docs/ref/contrib/formtools/form-preview.txt index ece69067ee..a2cbea704a 100644 --- a/docs/ref/contrib/formtools/form-preview.txt +++ b/docs/ref/contrib/formtools/form-preview.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-formtools-form-preview: - ============ Form preview ============ diff --git a/docs/ref/contrib/formtools/form-wizard.txt b/docs/ref/contrib/formtools/form-wizard.txt index 5ef862ce3d..ab7b4829c9 100644 --- a/docs/ref/contrib/formtools/form-wizard.txt +++ b/docs/ref/contrib/formtools/form-wizard.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-formtools-form-wizard: - =========== Form wizard =========== @@ -10,7 +8,7 @@ Form wizard .. versionadded:: 1.0 Django comes with an optional "form wizard" application that splits -:ref:`forms <topics-forms-index>` across multiple Web pages. It maintains +:doc:`forms </topics/forms/index>` across multiple Web pages. It maintains state in hashed HTML :samp:`<input type="hidden">` fields, and the data isn't processed server-side until the final form is submitted. @@ -65,8 +63,8 @@ Defining ``Form`` classes The first step in creating a form wizard is to create the :class:`~django.forms.Form` classes. These should be standard -:class:`django.forms.Form` classes, covered in the :ref:`forms documentation -<topics-forms-index>`. These classes can live anywhere in your codebase, but +:class:`django.forms.Form` classes, covered in the :doc:`forms documentation +</topics/forms/index>`. These classes can live anywhere in your codebase, but convention is to put them in a file called :file:`forms.py` in your application. @@ -189,8 +187,10 @@ for the wizard to work properly. Hooking the wizard into a URLconf ================================= -Finally, give your new :class:`FormWizard` object a URL in ``urls.py``. The -wizard takes a list of your :class:`~django.forms.Form` objects as arguments:: +Finally, we need to specify which forms to use in the wizard, and then +deploy the new :class:`FormWizard` object a URL in ``urls.py``. The +wizard takes a list of your :class:`~django.forms.Form` objects as +arguments when you instantiate the Wizard:: from django.conf.urls.defaults import * from mysite.testapp.forms import ContactForm1, ContactForm2, ContactWizard diff --git a/docs/ref/contrib/formtools/index.txt b/docs/ref/contrib/formtools/index.txt index 92010a25db..f36470654a 100644 --- a/docs/ref/contrib/formtools/index.txt +++ b/docs/ref/contrib/formtools/index.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-formtools-index: - django.contrib.formtools ======================== diff --git a/docs/ref/contrib/gis/admin.txt b/docs/ref/contrib/gis/admin.txt index df93c58504..011bb6b6bf 100644 --- a/docs/ref/contrib/gis/admin.txt +++ b/docs/ref/contrib/gis/admin.txt @@ -54,7 +54,7 @@ GeoDjango's admin site existing geometry fields in the admin. .. note:: - + This is different from adding the geometry field to :attr:`~django.contrib.admin.ModelAdmin.readonly_fields`, which will only display the WKT of the geometry. Setting diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt index 2cb7f69887..3dd161ce1d 100644 --- a/docs/ref/contrib/gis/commands.txt +++ b/docs/ref/contrib/gis/commands.txt @@ -78,6 +78,6 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`. all applicable fields. .. django-admin-option:: --srid - + The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts to automatically determine of the SRID of the data source. diff --git a/docs/ref/contrib/gis/create_template_postgis-1.4.sh b/docs/ref/contrib/gis/create_template_postgis-1.4.sh index 74a6ef98d2..57a1373f96 100755 --- a/docs/ref/contrib/gis/create_template_postgis-1.4.sh +++ b/docs/ref/contrib/gis/create_template_postgis-1.4.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.4 +POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib createdb -E UTF8 template_postgis # Create the template spatial database. createlang -d template_postgis plpgsql # Adding PLPGSQL language support. psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';" diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index 6797ce2de0..fbced8e6e1 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -14,7 +14,7 @@ Spatial Backends .. versionadded:: 1.2 -In Django 1.2, support for :ref:`multiple databases <topics-db-multi-db>` was +In Django 1.2, support for :doc:`multiple databases </topics/db/multi-db>` was introduced. In order to support multiple databases, GeoDjango has segregated its functionality into full-fledged spatial database backends: @@ -26,7 +26,7 @@ its functionality into full-fledged spatial database backends: Database Settings Backwards-Compatibility ----------------------------------------- -In :ref:`Django 1.2 <releases-1.2>`, the way +In :doc:`Django 1.2 </releases/1.2>`, the way to :ref:`specify databases <specifying-databases>` in your settings was changed. The old database settings format (e.g., the ``DATABASE_*`` settings) is backwards compatible with GeoDjango, and will automatically use the @@ -60,7 +60,7 @@ MySQL's spatial extensions only support bounding box operations [``Contains``, ``Crosses``, ``Disjoint``, ``Intersects``, ``Overlaps``, ``Touches``, ``Within``] according to the specification. Those that are implemented return - the same result as the corresponding MBR-based functions. + the same result as the corresponding MBR-based functions. In other words, while spatial lookups such as :lookup:`contains <gis-contains>` are available in GeoDjango when using MySQL, the results returned are really @@ -92,8 +92,8 @@ model):: >>> z.save() Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a -different SRID value) than that of the field, then it will be implicitly -transformed into the SRID of the model's field, using the spatial database's +different SRID value) than that of the field, then it will be implicitly +transformed into the SRID of the model's field, using the spatial database's transform procedure:: >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal' @@ -133,17 +133,17 @@ For example:: >>> qs = Zipcode.objects.filter(poly__contains=pnt) In this case, ``poly`` is the geographic field, :lookup:`contains <gis-contains>` -is the spatial lookup type, and ``pnt`` is the parameter (which may be a +is the spatial lookup type, and ``pnt`` is the parameter (which may be a :class:`~django.contrib.gis.geos.GEOSGeometry` object or a string of GeoJSON , WKT, or HEXEWKB). -A complete reference can be found in the :ref:`spatial lookup reference +A complete reference can be found in the :ref:`spatial lookup reference <spatial-lookups>`. .. note:: - GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a - subclass of :class:`~django.db.models.QuerySet`. The + GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a + subclass of :class:`~django.db.models.QuerySet`. The :class:`GeoManager` instance attached to your model is what enables use of :class:`GeoQuerySet`. @@ -156,8 +156,8 @@ Introduction ------------ Distance calculations with spatial data is tricky because, unfortunately, the Earth is not flat. Some distance queries with fields in a geographic -coordinate system may have to be expressed differently because of -limitations in PostGIS. Please see the :ref:`selecting-an-srid` section +coordinate system may have to be expressed differently because of +limitations in PostGIS. Please see the :ref:`selecting-an-srid` section in the :ref:`ref-gis-model-api` documentation for more details. .. _distance-lookups-intro: @@ -181,7 +181,7 @@ The following distance lookups are available: Distance lookups take a tuple parameter comprising: -#. A geometry to base calculations from; and +#. A geometry to base calculations from; and #. A number or :class:`~django.contrib.gis.measure.Distance` object containing the distance. If a :class:`~django.contrib.gis.measure.Distance` object is used, @@ -191,8 +191,8 @@ to be in the units of the field. .. note:: - For users of PostGIS 1.4 and below, the routine ``ST_Distance_Sphere`` - is used by default for calculating distances on geographic coordinate systems + For users of PostGIS 1.4 and below, the routine ``ST_Distance_Sphere`` + is used by default for calculating distances on geographic coordinate systems (e.g., WGS84) -- which may only be called with point geometries [#fndistsphere14]_. Thus, geographic distance lookups on traditional PostGIS geometry columns are only allowed on :class:`PointField` model fields using a point for the @@ -212,24 +212,24 @@ to be in the units of the field. You can tell GeoDjango to use a geography column by setting ``geography=True`` in your field definition. -For example, let's say we have a ``SouthTexasCity`` model (from the -`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities +For example, let's say we have a ``SouthTexasCity`` model (from the +`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities in southern Texas:: from django.contrib.gis.db import models - + class SouthTexasCity(models.Model): name = models.CharField(max_length=30) - # A projected coordinate system (only valid for South Texas!) + # A projected coordinate system (only valid for South Texas!) # is used, units are in meters. - point = models.PointField(srid=32140) + point = models.PointField(srid=32140) objects = models.GeoManager() Then distance queries may be performed as follows:: >>> from django.contrib.gis.geos import * >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance`` - >>> from geoapp import SouthTexasCity + >>> from geoapp import SouthTexasCity # Distances will be calculated from this point, which does not have to be projected. >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) # If numeric parameter, units of field (meters in this case) are assumed. @@ -294,7 +294,7 @@ Lookup Type PostGIS Oracle MySQL [#]_ SpatiaLite ``GeoQuerySet`` Methods ----------------------- The following table provides a summary of what :class:`GeoQuerySet` methods -are available on each spatial backend. Please note that MySQL does not +are available on each spatial backend. Please note that MySQL does not support any of these methods, and is thus excluded from the table. ==================================== ======= ====== ========== @@ -330,7 +330,7 @@ Method PostGIS Oracle SpatiaLite :meth:`GeoQuerySet.translate` X X :meth:`GeoQuerySet.union` X X X :meth:`GeoQuerySet.unionagg` X X X -==================================== ======= ====== ========== +==================================== ======= ====== ========== .. rubric:: Footnotes .. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry). diff --git a/docs/ref/contrib/gis/deployment.txt b/docs/ref/contrib/gis/deployment.txt index 2cfd367fac..fa7fe69267 100644 --- a/docs/ref/contrib/gis/deployment.txt +++ b/docs/ref/contrib/gis/deployment.txt @@ -6,15 +6,15 @@ Deploying GeoDjango GeoDjango uses the GDAL geospatial library which is not thread safe at this time. Thus, it is *highly* recommended - to not use threading when deploying -- in other words, use a + to not use threading when deploying -- in other words, use a an appropriate configuration of Apache or the prefork method when using FastCGI through another web server. Apache ====== -In this section there are some example ``VirtualHost`` directives for +In this section there are some example ``VirtualHost`` directives for when deploying using either ``mod_python`` or ``mod_wsgi``. At this -time, we recommend ``mod_wsgi``, as it is now officially recommended +time, we recommend ``mod_wsgi``, as it is now officially recommended way to deploy Django applications with Apache. Moreover, if ``mod_python`` is used, then a prefork version of Apache must also be used. As long as ``mod_wsgi`` is configured correctly, it does not @@ -23,7 +23,7 @@ matter whether the version of Apache is prefork or worker. .. note:: The ``Alias`` and ``Directory`` configurations in the the examples - below use an example path to a system-wide installation folder of Django. + below use an example path to a system-wide installation folder of Django. Substitute in an appropriate location, if necessary, as it may be different than the path on your system. @@ -36,7 +36,7 @@ Example:: WSGIDaemonProcess geodjango user=geo group=geo processes=5 threads=1 WSGIProcessGroup geodjango WSGIScriptAlias / /home/geo/geodjango/world.wsgi - + Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/" <Directory "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"> Order allow,deny @@ -44,25 +44,31 @@ Example:: Allow from all IndexOptions FancyIndexing </Directory> - + </VirtualHost> .. warning:: If the ``WSGIDaemonProcess`` attribute ``threads`` is not set to ``1``, then - Apache may crash when running your GeoDjango application. Increase the + Apache may crash when running your GeoDjango application. Increase the number of ``processes`` instead. For more information, please consult Django's -:ref:`mod_wsgi documentation <howto-deployment-modwsgi>`. +:doc:`mod_wsgi documentation </howto/deployment/modwsgi>`. ``mod_python`` -------------- +.. warning:: + Support for mod_python will be deprecated in a future release of Django. If + you are configuring a new deployment, you are strongly encouraged to + consider using :doc:`mod_wsgi </howto/deployment/modwsgi>` or any of the + other :doc:`supported backends </howto/deployment/index>`. + Example:: <VirtualHost *:80> - + <Location "/"> SetHandler mod_python PythonHandler django.core.handlers.modpython @@ -70,12 +76,12 @@ Example:: PythonDebug On PythonPath "['/var/www/apps'] + sys.path" </Location> - + Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/" <Location "/media"> SetHandler None </Location> - + </VirtualHost> .. warning:: @@ -84,7 +90,7 @@ Example:: else your GeoDjango application may crash Apache. For more information, please consult Django's -:ref:`mod_python documentation <howto-deployment-modpython>`. +:doc:`mod_python documentation </howto/deployment/modpython>`. Lighttpd ======== diff --git a/docs/ref/contrib/gis/feeds.txt b/docs/ref/contrib/gis/feeds.txt index bb9c12ae5d..7c3a2d011c 100644 --- a/docs/ref/contrib/gis/feeds.txt +++ b/docs/ref/contrib/gis/feeds.txt @@ -1,5 +1,3 @@ -.. _ref-gis-feeds: - ================ Geographic Feeds ================ @@ -8,10 +6,10 @@ Geographic Feeds :synopsis: GeoDjango's framework for generating spatial feeds. GeoDjango has its own :class:`Feed` subclass that may embed location information -in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or +in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or `W3C Geo`_ standards. Because GeoDjango's syndication API is a superset of -Django's, please consult `Django's syndication documentation <ref-contrib-syndication>` -for details on general usage. +Django's, please consult :doc:`Django's syndication documentation +</ref/contrib/syndication>` for details on general usage. .. _W3C Geo: http://www.w3.org/2003/01/geo/ @@ -28,7 +26,7 @@ API Reference .. class:: Feed - In addition to methods provided by + In addition to methods provided by the :class:`django.contrib.syndication.feeds.Feed` base class, GeoDjango's ``Feed`` class provides the following overrides. Note that these overrides may be done in multiple ways:: diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index c413ff4157..69f0c02e86 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -14,12 +14,12 @@ GeoQuerySet API Reference Spatial Lookups =============== -Just like when using the the :ref:`queryset-api`, interaction +Just like when using the the :ref:`queryset-api`, interaction with ``GeoQuerySet`` by :ref:`chaining filters <chaining-filters>`. Instead of the regular Django :ref:`field-lookups`, the spatial lookups in this section are available for :class:`GeometryField`. -For an introduction, see the :ref:`spatial lookups introduction +For an introduction, see the :ref:`spatial lookups introduction <spatial-lookups-intro>`. For an overview of what lookups are compatible with a particular spatial backend, refer to the :ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`. @@ -31,7 +31,7 @@ bbcontains *Availability*: PostGIS, MySQL, SpatiaLite -Tests if the geometry field's bounding box completely contains the lookup +Tests if the geometry field's bounding box completely contains the lookup geometry's bounding box. Example:: @@ -53,7 +53,7 @@ bboverlaps *Availability*: PostGIS, MySQL, SpatiaLite -Tests if the geometry field's bounding box overlaps the lookup geometry's +Tests if the geometry field's bounding box overlaps the lookup geometry's bounding box. Example:: @@ -277,9 +277,9 @@ the values given in the given pattern. This lookup requires a tuple parameter, PostGIS & SpatiaLite ~~~~~~~~~~~~~~~~~~~~ -On these spatial backends the intersection pattern is a string comprising -nine characters, which define intersections between the interior, boundary, -and exterior of the geometry field and the lookup geometry. +On these spatial backends the intersection pattern is a string comprising +nine characters, which define intersections between the interior, boundary, +and exterior of the geometry field and the lookup geometry. The intersection pattern matrix may only use the following characters: ``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune" a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_ @@ -302,7 +302,7 @@ Oracle ~~~~~~ Here the relation pattern is compreised at least one of the nine relation -strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``, +strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``, ``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and ``ANYINTERACT``. Multiple strings may be combined with the logical Boolean operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_ The relation @@ -312,7 +312,7 @@ Example:: Zipcode.objects.filter(poly__relate(geom, 'anyinteract')) -Oracle SQL equivalent:: +Oracle SQL equivalent:: SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract') @@ -403,7 +403,7 @@ overlaps_left *Availability*: PostGIS -Tests if the geometry field's bounding box overlaps or is to the left of the lookup +Tests if the geometry field's bounding box overlaps or is to the left of the lookup geometry's bounding box. Example:: @@ -422,7 +422,7 @@ overlaps_right *Availability*: PostGIS -Tests if the geometry field's bounding box overlaps or is to the right of the lookup +Tests if the geometry field's bounding box overlaps or is to the right of the lookup geometry's bounding box. Example:: @@ -440,7 +440,7 @@ overlaps_above *Availability*: PostGIS -Tests if the geometry field's bounding box overlaps or is above the lookup +Tests if the geometry field's bounding box overlaps or is above the lookup geometry's bounding box. Example:: @@ -458,7 +458,7 @@ overlaps_below *Availability*: PostGIS -Tests if the geometry field's bounding box overlaps or is below the lookup +Tests if the geometry field's bounding box overlaps or is below the lookup geometry's bounding box. Example:: @@ -476,7 +476,7 @@ strictly_above *Availability*: PostGIS -Tests if the geometry field's bounding box is strictly above the lookup +Tests if the geometry field's bounding box is strictly above the lookup geometry's bounding box. Example:: @@ -494,7 +494,7 @@ strictly_below *Availability*: PostGIS -Tests if the geometry field's bounding box is strictly above the lookup +Tests if the geometry field's bounding box is strictly above the lookup geometry's bounding box. Example:: @@ -662,7 +662,7 @@ Keyword Argument Description ===================== ===================================================== ``field_name`` By default, ``GeoQuerySet`` methods use the first geographic field encountered in the model. This - keyword should be used to specify another + keyword should be used to specify another geographic field (e.g., ``field_name='point2'``) when there are multiple geographic fields in a model. @@ -670,7 +670,7 @@ Keyword Argument Description used on geometry fields in models that are related via a ``ForeignKey`` relation (e.g., ``field_name='related__point'``). - + ``model_att`` By default, ``GeoQuerySet`` methods typically attach their output in an attribute with the same name as the ``GeoQuerySet`` method. Setting this keyword @@ -679,12 +679,12 @@ Keyword Argument Description ``qs = Zipcode.objects.centroid(model_att='c')`` will attach the centroid of the ``Zipcode`` geometry field in a ``c`` attribute on every model rather than in a - ``centroid`` attribute. + ``centroid`` attribute. - This keyword is required if - a method name clashes with an existing - ``GeoQuerySet`` method -- if you wanted to use the - ``area()`` method on model with a ``PolygonField`` + This keyword is required if + a method name clashes with an existing + ``GeoQuerySet`` method -- if you wanted to use the + ``area()`` method on model with a ``PolygonField`` named ``area``, for example. ===================== ===================================================== @@ -705,12 +705,12 @@ each element of this GeoQuerySet. .. method:: GeoQuerySet.distance(geom, **kwargs) -This method takes a geometry as a parameter, and attaches a ``distance`` -attribute to every model in the returned queryset that contains the +This method takes a geometry as a parameter, and attaches a ``distance`` +attribute to every model in the returned queryset that contains the distance (as a :class:`~django.contrib.gis.measure.Distance` object) to the given geometry. -In the following example (taken from the `GeoDjango distance tests`__), -the distance from the `Tasmanian`__ city of Hobart to every other +In the following example (taken from the `GeoDjango distance tests`__), +the distance from the `Tasmanian`__ city of Hobart to every other :class:`PointField` in the ``AustraliaCity`` queryset is calculated:: >>> pnt = AustraliaCity.objects.get(name='Hobart').point @@ -732,7 +732,7 @@ the distance from the `Tasmanian`__ city of Hobart to every other Because the ``distance`` attribute is a :class:`~django.contrib.gis.measure.Distance` object, you can easily express the value in the units of your choice. For example, ``city.distance.mi`` is - the distance value in miles and ``city.distance.km`` is the distance value + the distance value in miles and ``city.distance.km`` is the distance value in kilometers. See the :ref:`ref-measure` for usage details and the list of :ref:`supported_units`. @@ -867,9 +867,9 @@ then 4326 (WGS84) is used by default. geometry is placed on the models. .. note:: - - What spatial reference system an integer SRID corresponds to may depend on - the spatial database used. In other words, the SRID numbers used for Oracle + + What spatial reference system an integer SRID corresponds to may depend on + the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS. Example:: @@ -903,7 +903,7 @@ to each element of the ``GeoQuerySet`` that is the result of the operation. .. method:: GeoQuerySet.difference(geom) Returns the spatial difference of the geographic field with the given -geometry in a ``difference`` attribute on each element of the +geometry in a ``difference`` attribute on each element of the ``GeoQuerySet``. @@ -913,7 +913,7 @@ geometry in a ``difference`` attribute on each element of the .. method:: GeoQuerySet.intersection(geom) Returns the spatial intersection of the geographic field with the -given geometry in an ``intersection`` attribute on each element of the +given geometry in an ``intersection`` attribute on each element of the ``GeoQuerySet``. ``sym_difference`` @@ -937,7 +937,7 @@ geometry in an ``union`` attribute on each element of the Geometry Output --------------- -The following ``GeoQuerySet`` methods will return an attribute that has the value +The following ``GeoQuerySet`` methods will return an attribute that has the value of the geometry field in each model converted to the requested output format. ``geohash`` @@ -967,8 +967,8 @@ Attaches a ``geojson`` attribute to every model in the queryset that contains th ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``precision`` It may be used to specify the number of significant - digits for the coordinates in the GeoJSON +``precision`` It may be used to specify the number of significant + digits for the coordinates in the GeoJSON representation -- the default value is 8. ``crs`` Set this to ``True`` if you want the coordinate @@ -988,8 +988,8 @@ __ http://geojson.org/ *Availability*: PostGIS, Oracle -Attaches a ``gml`` attribute to every model in the queryset that contains the -`Geographic Markup Language (GML)`__ representation of the geometry. +Attaches a ``gml`` attribute to every model in the queryset that contains the +`Geographic Markup Language (GML)`__ representation of the geometry. Example:: @@ -1000,9 +1000,9 @@ Example:: ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``precision`` This keyword is for PostGIS only. It may be used - to specify the number of significant digits for the - coordinates in the GML representation -- the default +``precision`` This keyword is for PostGIS only. It may be used + to specify the number of significant digits for the + coordinates in the GML representation -- the default value is 8. ``version`` This keyword is for PostGIS only. It may be used to @@ -1019,9 +1019,9 @@ __ http://en.wikipedia.org/wiki/Geography_Markup_Language *Availability*: PostGIS -Attaches a ``kml`` attribute to every model in the queryset that contains the -`Keyhole Markup Language (KML)`__ representation of the geometry fields. It -should be noted that the contents of the KML are transformed to WGS84 if +Attaches a ``kml`` attribute to every model in the queryset that contains the +`Keyhole Markup Language (KML)`__ representation of the geometry fields. It +should be noted that the contents of the KML are transformed to WGS84 if necessary. Example:: @@ -1033,8 +1033,8 @@ Example:: ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``precision`` This keyword may be used to specify the number of - significant digits for the coordinates in the KML +``precision`` This keyword may be used to specify the number of + significant digits for the coordinates in the KML representation -- the default value is 8. ===================== ===================================================== @@ -1054,11 +1054,11 @@ the `Scalable Vector Graphics (SVG)`__ path data of the geometry fields. Keyword Argument Description ===================== ===================================================== ``relative`` If set to ``True``, the path data will be implemented - in terms of relative moves. Defaults to ``False``, + in terms of relative moves. Defaults to ``False``, meaning that absolute moves are used instead. -``precision`` This keyword may be used to specify the number of - significant digits for the coordinates in the SVG +``precision`` This keyword may be used to specify the number of + significant digits for the coordinates in the SVG representation -- the default value is 8. ===================== ===================================================== @@ -1129,7 +1129,7 @@ dissolving boundaries. *Availability*: PostGIS, Oracle -Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the +Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the lower left coordinate and the upper right coordinate. Example:: @@ -1163,7 +1163,7 @@ Example:: *Availability*: PostGIS -Returns a ``LineString`` constructed from the point field geometries in the +Returns a ``LineString`` constructed from the point field geometries in the ``GeoQuerySet``. Currently, ordering the queryset has no effect. Example:: @@ -1184,25 +1184,25 @@ use of ``unionagg`` is processor intensive and may take a significant amount of time on large querysets. .. note:: - + If the computation time for using this method is too expensive, consider using :meth:`GeoQuerySet.collect` instead. Example:: - + >>> u = Zipcode.objects.unionagg() # This may take a long time. >>> u = Zipcode.objects.filter(poly__within=bbox).unionagg() # A more sensible approach. ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``tolerance`` This keyword is for Oracle only. It is for the +``tolerance`` This keyword is for Oracle only. It is for the tolerance value used by the ``SDOAGGRTYPE`` - procedure; the `Oracle documentation`__ has more + procedure; the `Oracle documentation`__ has more details. ===================== ===================================================== -__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 +__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 Aggregate Functions ------------------- diff --git a/docs/ref/contrib/gis/install.txt b/docs/ref/contrib/gis/install.txt index 00d4e62e9f..ae36e167ae 100644 --- a/docs/ref/contrib/gis/install.txt +++ b/docs/ref/contrib/gis/install.txt @@ -13,7 +13,7 @@ In general, GeoDjango installation requires: 3. :ref:`geospatial_libs` Details for each of the requirements and installation instructions -are provided in the sections below. In addition, platform-specific +are provided in the sections below. In addition, platform-specific instructions are available for: * :ref:`macosx` @@ -23,10 +23,10 @@ instructions are available for: .. admonition:: Use the Source Because GeoDjango takes advantage of the latest in the open source geospatial - software technology, recent versions of the libraries are necessary. + software technology, recent versions of the libraries are necessary. If binary packages aren't available for your platform, :ref:`installation from source <build_from_source>` - may be required. When compiling the libraries from source, please follow the + may be required. When compiling the libraries from source, please follow the directions closely, especially if you're a beginner. Requirements @@ -37,8 +37,8 @@ Requirements Python 2.4+ ----------- Because of heavy use of the decorator syntax, Python 2.4 is minimum -version supported by GeoDjango. Python 2.5+ is recommended because the -`ctypes`__ module comes included; otherwise, 2.4 users will need to +version supported by GeoDjango. Python 2.5+ is recommended because the +`ctypes`__ module comes included; otherwise, 2.4 users will need to `download and install ctypes`__. __ http://docs.python.org/lib/module-ctypes.html @@ -50,18 +50,18 @@ Django ------ Because GeoDjango is included with Django, please refer to Django's -:ref:`installation instructions <intro-install>` for details on how to install. +:doc:`installation instructions </intro/install>` for details on how to install. .. _spatial_database: Spatial Database ---------------- -PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are +PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are the spatial databases currently supported. .. note:: - PostGIS is recommended, because it is the most mature and feature-rich + PostGIS is recommended, because it is the most mature and feature-rich open source spatial database. The geospatial libraries required for a GeoDjango installation depends @@ -81,7 +81,7 @@ SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires Geospatial Libraries -------------------- -GeoDjango uses and/or provides interfaces for the the following open source +GeoDjango uses and/or provides interfaces for the the following open source geospatial libraries: ======================== ==================================== ================================ ========================== @@ -117,7 +117,7 @@ Building from Source ==================== When installing from source on UNIX and GNU/Linux systems, please follow -the installation instructions carefully, and install the libraries in the +the installation instructions carefully, and install the libraries in the given order. If using MySQL or Oracle as the spatial database, only GEOS is required. @@ -147,13 +147,13 @@ internal geometry representation used by GeoDjango (it's behind the "lazy" geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``) directly from Python using ctypes. -First, download GEOS 3.2 from the refractions website and untar the source +First, download GEOS 3.2 from the refractions website and untar the source archive:: $ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2 $ tar xjf geos-3.2.2.tar.bz2 -Next, change into the directory where GEOS was unpacked, run the configure +Next, change into the directory where GEOS was unpacked, run the configure script, compile, and install:: $ cd geos-3.2.2 @@ -172,7 +172,7 @@ When GeoDjango can't find GEOS, this error is raised:: ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings. -The most common solution is to properly configure your :ref:`libsettings` *or* set +The most common solution is to properly configure your :ref:`libsettings` *or* set :ref:`geoslibrarypath` in your settings. If using a binary package of GEOS (e.g., on Ubuntu 8.10), you may need to :ref:`binutils`. @@ -191,7 +191,7 @@ C library. For example:: .. note:: - The setting must be the *full* path to the **C** shared library; in + The setting must be the *full* path to the **C** shared library; in other words you want to use ``libgeos_c.so``, not ``libgeos.so``. .. _proj4: @@ -199,7 +199,7 @@ C library. For example:: PROJ.4 ------ -`PROJ.4`_ is a library for converting geospatial data to different coordinate +`PROJ.4`_ is a library for converting geospatial data to different coordinate reference systems. First, download the PROJ.4 source code and datum shifting files [#]_:: @@ -228,12 +228,12 @@ PostGIS ------- `PostGIS`__ adds geographic object support to PostgreSQL, turning it -into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be +into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building PostGIS. .. note:: - The `psycopg2`_ module is required for use as the database adaptor + The `psycopg2`_ module is required for use as the database adaptor when using GeoDjango with PostGIS. .. _psycopg2: http://initd.org/projects/psycopg2 @@ -256,7 +256,7 @@ Finally, make and install:: .. note:: - GeoDjango does not automatically create a spatial database. Please + GeoDjango does not automatically create a spatial database. Please consult the section on :ref:`spatialdb_template` for more information. __ http://postgis.refractions.net/ @@ -267,7 +267,7 @@ GDAL ---- `GDAL`__ is an excellent open source geospatial library that has support for -reading most vector and raster spatial data formats. Currently, GeoDjango only +reading most vector and raster spatial data formats. Currently, GeoDjango only supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL. @@ -287,11 +287,11 @@ Configure, make and install:: .. note:: Because GeoDjango has it's own Python interface, the preceding instructions - do not build GDAL's own Python bindings. The bindings may be built by + do not build GDAL's own Python bindings. The bindings may be built by adding the ``--with-python`` flag when running ``configure``. See - `GDAL/OGR In Python`__ for more information on GDAL's bindings. + `GDAL/OGR In Python`__ for more information on GDAL's bindings. -If you have any problems, please see the troubleshooting section below for +If you have any problems, please see the troubleshooting section below for suggestions and solutions. __ http://trac.osgeo.org/gdal/ @@ -312,7 +312,7 @@ will be false:: >>> gdal.HAS_GDAL False -The solution is to properly configure your :ref:`libsettings` *or* set +The solution is to properly configure your :ref:`libsettings` *or* set :ref:`gdallibrarypath` in your settings. .. _gdallibrarypath: @@ -332,22 +332,22 @@ the GDAL library. For example:: Can't find GDAL data files (``GDAL_DATA``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When installed from source, GDAL versions 1.5.1 and below have an autoconf bug -that places data in the wrong location. [#]_ This can lead to error messages +When installed from source, GDAL versions 1.5.1 and below have an autoconf bug +that places data in the wrong location. [#]_ This can lead to error messages like this:: ERROR 4: Unable to open EPSG support file gcs.csv. ... OGRException: OGR failure. -The solution is to set the ``GDAL_DATA`` environment variable to the location of the -GDAL data files before invoking Python (typically ``/usr/local/share``; use +The solution is to set the ``GDAL_DATA`` environment variable to the location of the +GDAL data files before invoking Python (typically ``/usr/local/share``; use ``gdal-config --datadir`` to find out). For example:: $ export GDAL_DATA=`gdal-config --datadir` $ python manage.py shell -If using Apache, you may need to add this environment variable to your configuration +If using Apache, you may need to add this environment variable to your configuration file:: SetEnv GDAL_DATA /usr/local/share @@ -363,13 +363,13 @@ SpatiaLite Mac OS X users should follow the instructions in the :ref:`kyngchaos` section, as it is much easier than building from source. -`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured +`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured spatial database. Because SpatiaLite has special requirements, it typically -requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from +requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from source. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building SpatiaLite. -After installation is complete, don't forget to read the post-installation +After installation is complete, don't forget to read the post-installation docs on :ref:`create_spatialite_db`. __ http://www.gaia-gis.it/spatialite/index.html @@ -380,12 +380,12 @@ SQLite ^^^^^^ Typically, SQLite packages are not compiled to include the `R*Tree module`__ -- -thus it must be compiled from source. First download the latest amalgamation +thus it must be compiled from source. First download the latest amalgamation source archive from the `SQLite download page`__, and extract:: - $ wget http://www.sqlite.org/sqlite-amalgamation-3.6.22.tar.gz - $ tar xzf sqlite-amalgamation-3.6.22.tar.gz - $ cd sqlite-3.6.22 + $ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz + $ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz + $ cd sqlite-3.6.23.1 Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable needs to be customized so that SQLite knows to build the R*Tree module:: @@ -398,7 +398,7 @@ needs to be customized so that SQLite knows to build the R*Tree module:: .. note:: If using Ubuntu, installing a newer SQLite from source can be very difficult - because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which + because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which many other packages depend on. Unfortunately, the best solution at this time is to overwrite the existing library by adding ``--prefix=/usr`` to the ``configure`` command. @@ -420,7 +420,7 @@ SpatiaLite library source and tools bundle from the `download page`__:: $ tar xzf spatialite-tools-2.3.1.tar.gz Prior to attempting to build, please read the important notes below to see if -customization of the ``configure`` command is necessary. If not, then run the +customization of the ``configure`` command is necessary. If not, then run the ``configure`` script, make, and install for the SpatiaLite library:: $ cd libspatialite-amalgamation-2.3.1 @@ -431,7 +431,7 @@ customization of the ``configure`` command is necessary. If not, then run the Finally, do the same for the SpatiaLite tools:: - $ cd spatialite-tools-2.3.1 + $ cd spatialite-tools-2.3.1 $ ./configure # May need to modified, see notes below. $ make $ sudo make install @@ -440,21 +440,18 @@ Finally, do the same for the SpatiaLite tools:: .. note:: If you've installed GEOS and PROJ.4 from binary packages, you will have to specify - their paths when running the ``configure`` scripts for *both* the library and the - tools (the configure scripts look, by default, in ``/usr/local``). For example, + their paths when running the ``configure`` scripts for *both* the library and the + tools (the configure scripts look, by default, in ``/usr/local``). For example, on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be:: - + $ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib .. note:: - For Mac OS X users building from source, the SpatiaLite library *and* tools - need to be linked into the existing ``iconv`` library. While this happens - automatically on Linux, the ``configure`` scripts need to know about the - specific location on Mac OS X (via modification of the ``CFLAGS`` and - ``LDFLAGS`` environment variables prior to configuration):: + For Mac OS X users building from source, the SpatiaLite library *and* tools + need to have their ``target`` configured:: - $ CFLAGS=-I/usr/include LDFLAGS="-L/usr/lib -liconv" ./configure + $ ./configure --target=macosx __ http://www.gaia-gis.it/spatialite/sources.html @@ -466,7 +463,7 @@ pysqlite2 Because SpatiaLite must be loaded as an external extension, it requires the ``enable_load_extension`` method, which is only available in versions 2.5+. Thus, download pysqlite2 2.6, and untar:: - + $ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz $ tar xzf pysqlite-2.6.0.tar.gz $ cd pysqlite-2.6.0 @@ -487,7 +484,7 @@ to look like the following:: ``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs`` and ``library_dirs`` settings are uncommented and set to the appropriate path if the SQLite header files and libraries are not in ``/usr/include`` - and ``/usr/lib``, respectively. + and ``/usr/lib``, respectively. After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script to build and install:: @@ -503,7 +500,7 @@ Creating a Spatial Database Template for PostGIS ------------------------------------------------ Creating a spatial database with PostGIS is different than normal because -additional SQL must be loaded to enable spatial functionality. Because of +additional SQL must be loaded to enable spatial functionality. Because of the steps in this process, it's better to create a database template that can be reused later. @@ -521,7 +518,7 @@ user. For example, you can use the following to become the ``postgres`` user:: version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``. The example below assumes PostGIS 1.5, thus you may need to modify - ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific + ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific version of PostGIS you are using. Once you're a database super user, then you may execute the following commands @@ -601,7 +598,7 @@ __ http://www.gaia-gis.it/spatialite/resources.html Add ``django.contrib.gis`` to ``INSTALLED_APPS`` ------------------------------------------------ -Like other Django contrib applications, you will *only* need to add +Like other Django contrib applications, you will *only* need to add :mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings. This is the so that ``gis`` templates can be located -- if not done, then features such as the geographic admin or KML sitemaps will not function properly. @@ -633,7 +630,7 @@ Invoke the Django shell from your project and execute the In Django 1.1 the name of this function is ``add_postgis_srs``. This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent) -table, making it possible for the spatial database to transform coordinates in +table, making it possible for the spatial database to transform coordinates in this projection. You only need to execute this command *once* per spatial database. Troubleshooting @@ -643,8 +640,8 @@ If you can't find the solution to your problem here then participate in the community! You can: * Join the ``#geodjango`` IRC channel on FreeNode (may be accessed on the - web via `Mibbit`__). Please be patient and polite -- while you may not - get an immediate response, someone will attempt to answer your question + web via `Mibbit`__). Please be patient and polite -- while you may not + get an immediate response, someone will attempt to answer your question as soon as they see it. * Ask your question on the `GeoDjango`__ mailing list. * File a ticket on the `Django trac`__ if you think there's a bug. Make @@ -662,7 +659,7 @@ Library Environment Settings By far, the most common problem when installing GeoDjango is that the external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_ -Typically, the cause of this problem is that the operating system isn't aware +Typically, the cause of this problem is that the operating system isn't aware of the directory where the libraries built from source were installed. In general, the library path may be set on a per-user basis by setting @@ -673,9 +670,9 @@ system. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A user may set this environment variable to customize the library paths -they want to use. The typical library directory for software +they want to use. The typical library directory for software built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs -to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user +to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user could place the following in their bash profile:: export LD_LIBRARY_PATH=/usr/local/lib @@ -685,7 +682,7 @@ Setting System Library Path On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include additional paths from files in another directory, such as ``/etc/ld.so.conf.d``. -As the root user, add the custom library path (like ``/usr/local/lib``) on a +As the root user, add the custom library path (like ``/usr/local/lib``) on a new line in ``ld.so.conf``. This is *one* example of how to do so:: $ sudo echo /usr/local/lib >> /etc/ld.so.conf @@ -705,9 +702,9 @@ Install ``binutils`` GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python module) to discover libraries. The ``find_library`` routine uses a program -called ``objdump`` (part of the ``binutils`` package) to verify a shared +called ``objdump`` (part of the ``binutils`` package) to verify a shared library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your -Linux system then Python's ctypes may not be able to find your library even if +Linux system then Python's ctypes may not be able to find your library even if your library path is set correctly and geospatial libraries were built perfectly. The ``binutils`` package may be installed on Debian and Ubuntu systems using the @@ -738,10 +735,10 @@ several different options for installing GeoDjango. These options are: .. note:: Currently, the easiest and recommended approach for installing GeoDjango - on OS X is to use the KyngChaos packages. + on OS X is to use the KyngChaos packages. -This section also includes instructions for installing an upgraded version -of :ref:`macosx_python` from packages provided by the Python Software +This section also includes instructions for installing an upgraded version +of :ref:`macosx_python` from packages provided by the Python Software Foundation, however, this is not required. .. _macosx_python: @@ -750,8 +747,8 @@ Python ^^^^^^ Although OS X comes with Python installed, users can use framework -installers (`2.5`__ and `2.6`__ are available) provided by -the Python Software Foundation. An advantage to using the installer is +installers (`2.5`__ and `2.6`__ are available) provided by +the Python Software Foundation. An advantage to using the installer is that OS X's Python will remain "pristine" for internal operating system use. @@ -759,7 +756,7 @@ __ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg __ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg .. note:: - + You will need to modify the ``PATH`` environment variable in your ``.profile`` file so that the new version of Python is used when ``python`` is entered at the command-line:: @@ -771,15 +768,15 @@ __ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg KyngChaos Packages ^^^^^^^^^^^^^^^^^^ -William Kyngesburye provides a number of `geospatial library binary packages`__ -that make it simple to get GeoDjango installed on OS X without compiling +William Kyngesburye provides a number of `geospatial library binary packages`__ +that make it simple to get GeoDjango installed on OS X without compiling them from source. However, the `Apple Developer Tools`_ are still necessary for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS) -and :ref:`pysqlite2_kyngchaos` (for SpatiaLite). +and :ref:`pysqlite2_kyngchaos` (for SpatiaLite). .. note:: - SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section + SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section after installing the packages for additional instructions. Download the framework packages for: @@ -804,8 +801,8 @@ your ``.profile`` to be able to run the package programs from the command-line:: export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH export PATH=/usr/local/pgsql/bin:$PATH -__ http://www.kyngchaos.com/wiki/software:frameworks -__ http://www.kyngchaos.com/wiki/software:postgres +__ http://www.kyngchaos.com/software/frameworks +__ http://www.kyngchaos.com/software/postgres .. note:: @@ -837,7 +834,7 @@ described above, ``psycopg2`` may be installed using the following command:: pysqlite2 ~~~~~~~~~ -Follow the :ref:`pysqlite2` source install instructions, however, +Follow the :ref:`pysqlite2` source install instructions, however, when editing the ``setup.cfg`` use the following instead:: [build_ext] @@ -854,7 +851,7 @@ SpatiaLite When :ref:`create_spatialite_db`, the ``spatialite`` program is required. However, instead of attempting to compile the SpatiaLite tools from source, -download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a +download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a location available in your ``PATH``. For example:: $ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz @@ -890,9 +887,9 @@ __ http://www.finkproject.org/ MacPorts ^^^^^^^^ -`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh +`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh computers running OS X. Because MacPorts still builds the software from source, -the `Apple Developer Tools`_ are required. +the `Apple Developer Tools`_ are required. Summary:: @@ -901,7 +898,7 @@ Summary:: $ sudo port install proj $ sudo port install postgis $ sudo port install gdal - $ sudo port install libgeoip + $ sudo port install libgeoip .. note:: @@ -932,9 +929,9 @@ Ubuntu 8.04 and lower ~~~~~~~~~~~~~~ -The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages, -which is incompatible with GeoDjango. Thus, do *not* use the binary packages -for GEOS or PostGIS and build some prerequisites from source, per the instructions +The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages, +which is incompatible with GeoDjango. Thus, do *not* use the binary packages +for GEOS or PostGIS and build some prerequisites from source, per the instructions in this document; however, it is okay to use the PostgreSQL binary packages. For more details, please see the Debian instructions for :ref:`etch` below. @@ -973,11 +970,11 @@ Optional packages to consider: * ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation .. note:: - + The Ubuntu ``proj`` package does not come with the datum shifting files - installed, which will cause problems with the geographic admin because + installed, which will cause problems with the geographic admin because the ``null`` datum grid is not available for transforming geometries to the - spherical mercator projection. A solution is to download the + spherical mercator projection. A solution is to download the datum-shifting files, create the grid file, and install it yourself:: $ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.tar.gz @@ -988,7 +985,7 @@ Optional packages to consider: $ sudo cp null /usr/share/proj Otherwise, the Ubuntu ``proj`` package is fine for general use as long as you - do not plan on doing any database transformation of geometries to the + do not plan on doing any database transformation of geometries to the Google projection (900913). .. note:: @@ -1035,14 +1032,14 @@ Optional packages: Source Packages ~~~~~~~~~~~~~~~ You will still have to install :ref:`geosbuild`, :ref:`proj4`, -:ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the +:ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the directions carefully. .. _lenny: 5.0 (Lenny) ^^^^^^^^^^^ -This version is comparable to Ubuntu :ref:`ibex`, so the command +This version is comparable to Ubuntu :ref:`ibex`, so the command is very similar:: $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools @@ -1089,13 +1086,13 @@ Python ^^^^^^ First, download the `Python 2.6 installer`__ from the Python website. Next, -execute the installer and use defaults, e.g., keep 'Install for all users' +execute the installer and use defaults, e.g., keep 'Install for all users' checked and the installation path set as ``C:\Python26``. .. note:: You may already have a version of Python installed in ``C:\python`` as ESRI - products sometimes install a copy there. *You should still install a + products sometimes install a copy there. *You should still install a fresh version of Python 2.6.* __ http://python.org/ftp/python/2.6.2/python-2.6.2.msi @@ -1110,21 +1107,21 @@ the EnterpriseDB website. PostgreSQL 8.3 is required because PostGIS is not available yet for 8.4. -After downloading, simply click on the installer, follow the -on-screen directions, and keep the default options (e.g., keep the installation +After downloading, simply click on the installer, follow the +on-screen directions, and keep the default options (e.g., keep the installation path as ``C:\Program Files\PostgreSQL\8.3``). .. note:: - This PostgreSQL installation process will create both a new windows user to be the - 'postgres service account' and a special 'postgres superuser' to own the database - cluster. You will be prompted to set a password for both users (make sure to write - them down!). To see basic details on the 'service user' account right click on - 'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools -> + This PostgreSQL installation process will create both a new windows user to be the + 'postgres service account' and a special 'postgres superuser' to own the database + cluster. You will be prompted to set a password for both users (make sure to write + them down!). To see basic details on the 'service user' account right click on + 'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools -> Computer Management -> System Tools -> Local Users and Groups. -If installed successfully, the PostgreSQL server will run in the background each time -the system as started as a Windows service. When finished, the installer should launch +If installed successfully, the PostgreSQL server will run in the background each time +the system as started as a Windows service. When finished, the installer should launch the Application Stack Builder (ASB) -- use this to install PostGIS, see instructions below for more details. A 'PostgreSQL 8.3' start menu group should be created that contains shortcuts for the ASB and 'Command Prompt', which launches a terminal window @@ -1135,22 +1132,22 @@ __ http://www.enterprisedb.com/products/pgdownload.do#windows PostGIS ^^^^^^^ -From the Application Stack Builder (Programs -> PostgreSQL 8.3), select -'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu. Next, +From the Application Stack Builder (Programs -> PostgreSQL 8.3), select +'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu. Next, select 'PostGIS 1.3.6 for PostgreSQL 8.3' from the 'Spatial Extensions' tree -in the list. Select only the default options during install (do not uncheck +in the list. Select only the default options during install (do not uncheck the option to create a default PostGIS database). .. note:: - You will be prompted to enter your 'postgres superuser' password in the + You will be prompted to enter your 'postgres superuser' password in the 'Database Connection Information' dialog. psycopg2 ^^^^^^^^ The ``psycopg2`` Python module provides the interface between Python and the -PostgreSQL database. Download the `Windows installer`__ (v2.0.10) and run +PostgreSQL database. Download the `Windows installer`__ (v2.0.10) and run using the default settings. [#]_ __ http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.10.win32-py2.6-pg8.3.7-release.exe @@ -1163,31 +1160,31 @@ of the process for installing GeoDjango on Windows platforms. The installer automatically installs Django 1.1, GDAL 1.6.0, PROJ 4.6.1 (including datum grid files), and configures the necessary environment variables. -Once the installer has completed, log out and log back in so that the +Once the installer has completed, log out and log back in so that the modifications to the system environment variables take effect, and you should be good to go. .. note:: The installer modifies the system ``Path`` environment variable to - include ``C:\Program Files\PostgreSQL\8.3\bin`` and + include ``C:\Program Files\PostgreSQL\8.3\bin`` and ``C:\Program Files\GeoDjango\bin``. This is required so that Python may find the GEOS DLL provided by PostGIS and the GDAL DLL provided - by the installer. The installer also sets the ``GDAL_DATA`` and + by the installer. The installer also sets the ``GDAL_DATA`` and ``PROJ_LIB`` environment variables. __ http://geodjango.org/windows/GeoDjango_Installer.exe .. rubric:: Footnotes .. [#] The datum shifting files are needed for converting data to and from certain projections. - For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_ - requires the ``null`` grid file only included in the extra datum shifting files. + For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_ + requires the ``null`` grid file only included in the extra datum shifting files. It is easier to install the shifting files now, then to have debug a problem caused by their absence later. .. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL. .. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_. .. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_ - routine from ``ctypes.util`` to locate shared libraries. -.. [#] The ``psycopg2`` Windows installers are packaged and maintained by - `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. -.. [#] The source code for the installer is available in the `nsis_installer <http://geodjango.org/hg/nsis_installer/>`_ + routine from ``ctypes.util`` to locate shared libraries. +.. [#] The ``psycopg2`` Windows installers are packaged and maintained by + `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. +.. [#] The source code for the installer is available in the `nsis_installer <http://geodjango.org/hg/nsis_installer/>`_ GeoDjango mercurial repository. diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index a423259c11..0b09e176f6 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -14,7 +14,7 @@ vector spatial data files (e.g. shapefiles) intoto GeoDjango models. This utility grew out of the author's personal needs to eliminate the code repetition that went into pulling geometries and fields out of -a vector layer, converting to another coordinate system (e.g. WGS84), and +a vector layer, converting to another coordinate system (e.g. WGS84), and then inserting into a GeoDjango model. .. note:: @@ -27,7 +27,7 @@ then inserting into a GeoDjango model. that :class:`LayerMapping` is using too much memory, set :setting:`DEBUG` to ``False`` in your settings. When :setting:`DEBUG` is set to ``True``, Django :ref:`automatically logs <faq-see-raw-sql-queries>` - *every* SQL query -- thus, when SQL statements contain geometries, it is + *every* SQL query -- thus, when SQL statements contain geometries, it is easy to consume more memory than is typical. Example @@ -50,7 +50,7 @@ Example DATUM["WGS_1984", SPHEROID["WGS_1984",6378137,298.257223563]], PRIMEM["Greenwich",0], - UNIT["Degree",0.017453292519943295]] + UNIT["Degree",0.017453292519943295]] 2. Now we define our corresponding Django model (make sure to use ``syncdb``):: @@ -71,16 +71,16 @@ Example >>> mapping = {'name' : 'str', # The 'name' model field maps to the 'str' layer field. 'poly' : 'POLYGON', # For geometry fields use OGC name. } # The mapping is a dictionary - >>> lm = LayerMapping(TestGeo, 'test_poly.shp', mapping) - >>> lm.save(verbose=True) # Save the layermap, imports the data. + >>> lm = LayerMapping(TestGeo, 'test_poly.shp', mapping) + >>> lm.save(verbose=True) # Save the layermap, imports the data. Saved: Name: 1 Saved: Name: 2 Saved: Name: 3 Here, :class:`LayerMapping` just transformed the three geometries from the shapefile in their original spatial reference system (WGS84) to the spatial -reference system of the GeoDjango model (NAD83). If no spatial reference -system is defined for the layer, use the ``source_srs`` keyword with a +reference system of the GeoDjango model (NAD83). If no spatial reference +system is defined for the layer, use the ``source_srs`` keyword with a :class:`~django.contrib.gis.gdal.SpatialReference` object to specify one. ``LayerMapping`` API @@ -106,43 +106,43 @@ Argument Description model field is a geographic then it should correspond to the OGR geometry type, e.g., ``'POINT'``, ``'LINESTRING'``, ``'POLYGON'``. -================= ========================================================= +================= ========================================================= ===================== ===================================================== Keyword Arguments -===================== ===================================================== -``layer`` The index of the layer to use from the Data Source +===================== ===================================================== +``layer`` The index of the layer to use from the Data Source (defaults to 0) - -``source_srs`` Use this to specify the source SRS manually (for - example, some shapefiles don't come with a '.prj' - file). An integer SRID, WKT or PROJ.4 strings, and - :class:`django.contrib.gis.gdal.SpatialReference` + +``source_srs`` Use this to specify the source SRS manually (for + example, some shapefiles don't come with a '.prj' + file). An integer SRID, WKT or PROJ.4 strings, and + :class:`django.contrib.gis.gdal.SpatialReference` objects are accepted. - -``encoding`` Specifies the character set encoding of the strings - in the OGR data source. For example, ``'latin-1'``, - ``'utf-8'``, and ``'cp437'`` are all valid encoding + +``encoding`` Specifies the character set encoding of the strings + in the OGR data source. For example, ``'latin-1'``, + ``'utf-8'``, and ``'cp437'`` are all valid encoding parameters. - -``transaction_mode`` May be ``'commit_on_success'`` (default) or + +``transaction_mode`` May be ``'commit_on_success'`` (default) or ``'autocommit'``. - -``transform`` Setting this to False will disable coordinate + +``transform`` Setting this to False will disable coordinate transformations. In other words, geometries will be inserted into the database unmodified from their original state in the data source. - + ``unique`` Setting this to the name, or a tuple of names, from the given model will create models unique - only to the given name(s). Geometries will from - each feature will be added into the collection - associated with the unique model. Forces + only to the given name(s). Geometries will from + each feature will be added into the collection + associated with the unique model. Forces the transaction mode to be ``'autocommit'``. ``using`` New in version 1.2. Sets the database to use when importing spatial data. Default is ``'default'`` -===================== ===================================================== +===================== ===================================================== ``save()`` Keyword Arguments ---------------------------- @@ -156,42 +156,42 @@ specific feature ranges. =========================== ================================================= Save Keyword Arguments Description =========================== ================================================= -``fid_range`` May be set with a slice or tuple of - (begin, end) feature ID's to map from +``fid_range`` May be set with a slice or tuple of + (begin, end) feature ID's to map from the data source. In other words, this - keyword enables the user to selectively + keyword enables the user to selectively import a subset range of features in the geographic data source. ``progress`` When this keyword is set, status information - will be printed giving the number of features - processed and successfully saved. By default, + will be printed giving the number of features + processed and successfully saved. By default, progress information will be printed every 1000 - features processed, however, this default may - be overridden by setting this keyword with an + features processed, however, this default may + be overridden by setting this keyword with an integer for the desired interval. -``silent`` By default, non-fatal error notifications are - printed to ``sys.stdout``, but this keyword may +``silent`` By default, non-fatal error notifications are + printed to ``sys.stdout``, but this keyword may be set to disable these notifications. -``step`` If set with an integer, transactions will - occur at every step interval. For example, if - ``step=1000``, a commit would occur after the +``step`` If set with an integer, transactions will + occur at every step interval. For example, if + ``step=1000``, a commit would occur after the 1,000th feature, the 2,000th feature etc. -``stream`` Status information will be written to this file - handle. Defaults to using ``sys.stdout``, but +``stream`` Status information will be written to this file + handle. Defaults to using ``sys.stdout``, but any object with a ``write`` method is supported. -``strict`` Execution of the model mapping will cease upon +``strict`` Execution of the model mapping will cease upon the first error encountered. The default value (``False``) behavior is to attempt to continue. -``verbose`` If set, information will be printed - subsequent to each model save +``verbose`` If set, information will be printed + subsequent to each model save executed on the database. =========================== ================================================= @@ -213,7 +213,7 @@ If you encounter the following error when using ``LayerMapping`` and MySQL:: OperationalError: (1153, "Got a packet bigger than 'max_allowed_packet' bytes") Then the solution is to increase the value of the ``max_allowed_packet`` -setting in your MySQL configuration. For example, the default value may +setting in your MySQL configuration. For example, the default value may be something low like one megabyte -- the setting may be modified in MySQL's configuration file (``my.cnf``) in the ``[mysqld]`` section:: diff --git a/docs/ref/contrib/gis/measure.txt b/docs/ref/contrib/gis/measure.txt index 8b9629ef80..6971788b4e 100644 --- a/docs/ref/contrib/gis/measure.txt +++ b/docs/ref/contrib/gis/measure.txt @@ -7,17 +7,17 @@ Measurement Objects .. module:: django.contrib.gis.measure :synopsis: GeoDjango's distance and area measurment objects. -The :mod:`django.contrib.gis.measure` module contains objects that allow -for convenient representation of distance and area units of measure. [#]_ -Specifically, it implements two objects, :class:`Distance` and -:class:`Area` -- both of which may be accessed via the +The :mod:`django.contrib.gis.measure` module contains objects that allow +for convenient representation of distance and area units of measure. [#]_ +Specifically, it implements two objects, :class:`Distance` and +:class:`Area` -- both of which may be accessed via the :class:`D` and :class:`A` convenience aliases, respectively. Example ======= -:class:`Distance` objects may be instantiated using a keyword argument indicating the -context of the units. In the example below, two different distance objects are +:class:`Distance` objects may be instantiated using a keyword argument indicating the +context of the units. In the example below, two different distance objects are instantiated in units of kilometers (``km``) and miles (``mi``):: >>> from django.contrib.gis.measure import Distance, D @@ -40,7 +40,7 @@ Moreover, arithmetic operations may be performed between the distance objects:: >>> print d1 + d2 # Adding 5 miles to 5 kilometers - 13.04672 km + 13.04672 km >>> print d2 - d1 # Subtracting 5 kilometers from 5 miles 1.89314403881 mi @@ -67,7 +67,7 @@ Supported units ================================= ======================================== Unit Attribute Full name or alias(es) ================================= ======================================== -``km`` Kilometre, Kilometer +``km`` Kilometre, Kilometer ``mi`` Mile ``m`` Meter, Metre ``yd`` Yard @@ -163,7 +163,7 @@ Measurement API 12.949940551680001 .. classmethod:: unit_attname(unit_name) - + Returns the area unit attribute name for the given full unit name. For example:: @@ -175,6 +175,6 @@ Measurement API Alias for :class:`Area` class. .. rubric:: Footnotes -.. [#] `Robert Coup <http://koordinates.com/>`_ is the initial author of the measure objects, - and was inspired by Brian Beck's work in `geopy <http://code.google.com/p/geopy/>`_ +.. [#] `Robert Coup <http://koordinates.com/>`_ is the initial author of the measure objects, + and was inspired by Brian Beck's work in `geopy <http://code.google.com/p/geopy/>`_ and Geoff Biggs' PhD work on dimensioned units for robotics. diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt index 7c83a7e267..cf73747463 100644 --- a/docs/ref/contrib/gis/model-api.txt +++ b/docs/ref/contrib/gis/model-api.txt @@ -8,11 +8,11 @@ GeoDjango Model API :synopsis: GeoDjango model and field API. This document explores the details of the GeoDjango Model API. Throughout this -section, we'll be using the following geographic model of a `ZIP code`__ as our +section, we'll be using the following geographic model of a `ZIP code`__ as our example:: from django.contrib.gis.db import models - + class Zipcode(models.Model): code = models.CharField(max_length=5) poly = models.PolygonField() @@ -23,7 +23,7 @@ __ http://en.wikipedia.org/wiki/ZIP_code Geometry Field Types ==================== -Each of the following geometry field types correspond with the +Each of the following geometry field types correspond with the OpenGIS Simple Features specification [#fnogc]_. ``GeometryField`` @@ -92,7 +92,7 @@ Selecting an SRID ^^^^^^^^^^^^^^^^^ Choosing an appropriate SRID for your model is an important decision that the -developer should consider carefully. The SRID is an integer specifier that +developer should consider carefully. The SRID is an integer specifier that corresponds to the projection system that will be used to interpret the data in the spatial database. [#fnsrid]_ Projection systems give the context to the coordinates that specify a location. Although the details of `geodesy`__ are @@ -105,7 +105,7 @@ location on the earth's surface. However, latitude and longitude are angles, not distances. [#fnharvard]_ In other words, while the shortest path between two points on a flat surface is a straight line, the shortest path between two points on a curved surface (such as the earth) is an *arc* of a `great circle`__. [#fnthematic]_ Thus, -additional computation is required to obtain distances in planar units (e.g., +additional computation is required to obtain distances in planar units (e.g., kilometers and miles). Using a geographic coordinate system may introduce complications for the developer later on. For example, PostGIS versions 1.4 and below do not have the capability to perform distance calculations between @@ -113,12 +113,12 @@ non-point geometries using geographic coordinate systems, e.g., constructing a query to find all points within 5 miles of a county boundary stored as WGS84. [#fndist]_ -Portions of the earth's surface may projected onto a two-dimensional, or +Portions of the earth's surface may projected onto a two-dimensional, or Cartesian, plane. Projected coordinate systems are especially convenient for region-specific applications, e.g., if you know that your database will -only cover geometries in `North Kansas`__, then you may consider using projection -system specific to that region. Moreover, projected coordinate systems are -defined in Cartesian units (such as meters or feet), easing distance +only cover geometries in `North Kansas`__, then you may consider using projection +system specific to that region. Moreover, projected coordinate systems are +defined in Cartesian units (such as meters or feet), easing distance calculations. .. note:: @@ -131,7 +131,7 @@ calculations. Additional Resources: -* `spatialreference.org`__: A Django-powered database of spatial reference +* `spatialreference.org`__: A Django-powered database of spatial reference systems. * `The State Plane Coordinate System`__: A website covering the various projection systems used in the United States. Much of the U.S. spatial @@ -150,7 +150,7 @@ __ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinate .. attribute:: GeometryField.spatial_index Defaults to ``True``. Creates a spatial index for the given geometry -field. +field. .. note:: @@ -185,7 +185,7 @@ three-dimensonal support. .. attribute:: GeometryField.geography If set to ``True``, this option will create a database column of -type geography, rather than geometry. Please refer to the +type geography, rather than geometry. Please refer to the :ref:`geography type <geography-type>` section below for more details. @@ -212,7 +212,7 @@ to degrees if called on a geometry column in WGS84). Because geography calculations involve more mathematics, only a subset of the PostGIS spatial lookups are available for the geography type. Practically, this means that in addition to the :ref:`distance lookups <distance-lookups>` -only the following additional :ref:`spatial lookups <spatial-lookups>` are +only the following additional :ref:`spatial lookups <spatial-lookups>` are available for geography columns: * :lookup:`bboverlaps` @@ -231,13 +231,13 @@ determining `when to use geography data type over geometry data type .. currentmodule:: django.contrib.gis.db.models .. class:: GeoManager -In order to conduct geographic queries, each geographic model requires +In order to conduct geographic queries, each geographic model requires a ``GeoManager`` model manager. This manager allows for the proper SQL -construction for geographic queries; thus, without it, all geographic filters +construction for geographic queries; thus, without it, all geographic filters will fail. It should also be noted that ``GeoManager`` is required even if the -model does not have a geographic field itself, e.g., in the case of a -``ForeignKey`` relation to a model with a geographic field. For example, -if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode`` +model does not have a geographic field itself, e.g., in the case of a +``ForeignKey`` relation to a model with a geographic field. For example, +if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode`` model:: from django.contrib.gis.db import models @@ -251,7 +251,7 @@ model:: zipcode = models.ForeignKey(Zipcode) objects = models.GeoManager() -The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, +The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, for example:: qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)') @@ -260,7 +260,7 @@ for example:: .. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999). .. [#fnogcsrid] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems). .. [#fnsrid] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <http://www.epsg.org>`_) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table. -.. [#fnharvard] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_. This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems. +.. [#fnharvard] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_. This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems. .. [#fnthematic] Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler, & Hugh H. Howard, *Thematic Cartography and Geographic Visualization* (Prentice Hall, 2nd edition), at Ch. 7.1.3. .. [#fndist] This limitation does not apply to PostGIS 1.5. It should be noted that even in previous versions of PostGIS, this isn't impossible using GeoDjango; you could for example, take a known point in a projected coordinate system, buffer it to the appropriate radius, and then perform an intersection operation with the buffer transformed to the geographic coordinate system. .. [#fngeography] Please refer to the `PostGIS Geography Type <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_Geography>`_ documentation for more details. diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt index b2513f670b..2e81510cd9 100644 --- a/docs/ref/contrib/gis/testing.txt +++ b/docs/ref/contrib/gis/testing.txt @@ -6,7 +6,7 @@ Testing GeoDjango Apps In Django 1.2, the addition of :ref:`spatial-backends` simplified the process of testing GeoDjango applications. Specifically, testing -GeoDjango applications is now the same as :ref:`topics-testing`. +GeoDjango applications is now the same as :doc:`/topics/testing`. Included in this documentation are some additional notes and settings for :ref:`testing-postgis` and :ref:`testing-spatialite` users. @@ -133,7 +133,7 @@ You will need to download the `initialization SQL`__ script for SpatiaLite:: If ``init_spatialite-2.3.sql`` is in the same path as your project's ``manage.py``, then all you have to do is:: - $ python manage.py test + $ python manage.py test Settings -------- @@ -166,9 +166,9 @@ must be used. To use this runner, configure :setting:`TEST_RUNNER` as follows:: .. note:: - In order to create a spatial database, the :setting:`DATABASE_USER` setting - (or :setting:`TEST_DATABASE_USER`, if optionally defined on Oracle) requires - elevated privileges. When using PostGIS or MySQL, the database user + In order to create a spatial database, the :setting:`USER` setting + (or :setting:`TEST_USER`, if optionally defined on Oracle) requires + elevated privileges. When using PostGIS or MySQL, the database user must have at least the ability to create databases. When testing on Oracle, the user should be a superuser. diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 5b535186f8..3a56c2e7c0 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -15,8 +15,8 @@ geographic web applications, like location-based services. Some features includ data formats. * Editing of geometry fields inside the admin. -This tutorial assumes a familiarity with Django; thus, if you're brand new to -Django please read through the :ref:`regular tutorial <intro-tutorial01>` to introduce +This tutorial assumes a familiarity with Django; thus, if you're brand new to +Django please read through the :doc:`regular tutorial </intro/tutorial01>` to introduce yourself with basic Django concepts. .. note:: @@ -27,12 +27,12 @@ yourself with basic Django concepts. This tutorial is going to guide you through guide the user through the creation of a geographic web application for viewing the `world borders`_. [#]_ Some of -the code used in this tutorial is taken from and/or inspired by the +the code used in this tutorial is taken from and/or inspired by the `GeoDjango basic apps`_ project. [#]_ .. note:: - Proceed through the tutorial sections sequentially for step-by-step + Proceed through the tutorial sections sequentially for step-by-step instructions. .. _OGC: http://www.opengeospatial.org/ @@ -51,11 +51,11 @@ Create a Spatial Database are already built into the database. First, a spatial database needs to be created for our project. If using -PostgreSQL and PostGIS, then the following commands will +PostgreSQL and PostGIS, then the following commands will create the database from a :ref:`spatial database template <spatialdb_template>`:: $ createdb -T template_postgis geodjango - + .. note:: This command must be issued by a database user that has permissions to @@ -65,9 +65,9 @@ create the database from a :ref:`spatial database template <spatialdb_template>` $ sudo su - postgres $ createuser --createdb geo $ exit - + Replace ``geo`` to correspond to the system login user name will be - connecting to the database. For example, ``johndoe`` if that is the + connecting to the database. For example, ``johndoe`` if that is the system user that will be running GeoDjango. Users of SQLite and SpatiaLite should consult the instructions on how @@ -92,7 +92,7 @@ Configure ``settings.py`` The ``geodjango`` project settings are stored in the ``settings.py`` file. Edit the database connection settings appropriately:: - DATABASES = { + DATABASES = { 'default': { 'ENGINE': 'django.contrib.gis.db.backends.postgis', 'NAME': 'geodjango', @@ -104,7 +104,7 @@ the database connection settings appropriately:: These database settings are for Django 1.2 and above. -In addition, modify the :setting:`INSTALLED_APPS` setting to include +In addition, modify the :setting:`INSTALLED_APPS` setting to include :mod:`django.contrib.admin`, :mod:`django.contrib.gis`, and ``world`` (our newly created application):: @@ -142,8 +142,8 @@ unzipped the world borders data set includes files with the following extensions * ``.shp``: Holds the vector data for the world borders geometries. * ``.shx``: Spatial index file for geometries stored in the ``.shp``. -* ``.dbf``: Database file for holding non-geometric attribute data - (e.g., integer and character fields). +* ``.dbf``: Database file for holding non-geometric attribute data + (e.g., integer and character fields). * ``.prj``: Contains the spatial reference information for the geographic data stored in the shapefile. @@ -153,7 +153,7 @@ __ http://en.wikipedia.org/wiki/Shapefile Use ``ogrinfo`` to examine spatial data --------------------------------------- -The GDAL ``ogrinfo`` utility is excellent for examining metadata about +The GDAL ``ogrinfo`` utility is excellent for examining metadata about shapefiles (or other vector data sources):: $ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp @@ -192,13 +192,13 @@ and use the ``-so`` option to get only important summary information:: LAT: Real (7.3) This detailed summary information tells us the number of features in the layer -(246), the geographical extent, the spatial reference system ("SRS WKT"), +(246), the geographical extent, the spatial reference system ("SRS WKT"), as well as detailed information for each attribute field. For example, ``FIPS: String (2.0)`` indicates that there's a ``FIPS`` character field with a maximum length of 2; similarly, ``LON: Real (8.3)`` is a floating-point field that holds a maximum of 8 digits up to three decimal places. Although this information may be found right on the `world borders`_ website, this shows -you how to determine this information yourself when such metadata is not +you how to determine this information yourself when such metadata is not provided. Geographic Models @@ -213,7 +213,7 @@ create a GeoDjango model to represent this data:: from django.contrib.gis.db import models class WorldBorders(models.Model): - # Regular Django fields corresponding to the attributes in the + # Regular Django fields corresponding to the attributes in the # world borders shapefile. name = models.CharField(max_length=50) area = models.IntegerField() @@ -227,7 +227,7 @@ create a GeoDjango model to represent this data:: lon = models.FloatField() lat = models.FloatField() - # GeoDjango-specific: a geometry field (MultiPolygonField), and + # GeoDjango-specific: a geometry field (MultiPolygonField), and # overriding the default manager with a GeoManager instance. mpoly = models.MultiPolygonField() objects = models.GeoManager() @@ -235,23 +235,23 @@ create a GeoDjango model to represent this data:: # So the model is pluralized correctly in the admin. class Meta: verbose_name_plural = "World Borders" - - # Returns the string representation of the model. + + # Returns the string representation of the model. def __unicode__(self): return self.name Two important things to note: 1. The ``models`` module is imported from :mod:`django.contrib.gis.db`. -2. The model overrides its default manager with +2. The model overrides its default manager with :class:`~django.contrib.gis.db.models.GeoManager`; this is *required* - to perform spatial queries. + to perform spatial queries. When declaring a geometry field on your model the default spatial reference system is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field coordinates are in longitude/latitude pairs in units of degrees. If you want the coordinate system to be different, then SRID of the geometry field may be customized by setting the ``srid`` -with an integer corresponding to the coordinate system of your choice. +with an integer corresponding to the coordinate system of your choice. __ http://en.wikipedia.org/wiki/SRID @@ -259,7 +259,7 @@ Run ``syncdb`` -------------- After you've defined your model, it needs to be synced with the spatial database. -First, let's look at the SQL that will generate the table for the ``WorldBorders`` +First, let's look at the SQL that will generate the table for the ``WorldBorders`` model:: $ python manage.py sqlall world @@ -295,7 +295,7 @@ If satisfied, you may then create this table in the database by running the Installing custom SQL for world.WorldBorders model The ``syncdb`` command may also prompt you to create an admin user; go ahead and -do so (not required now, may be done at any point in the future using the +do so (not required now, may be done at any point in the future using the ``createsuperuser`` management command). Importing Spatial Data @@ -303,11 +303,11 @@ Importing Spatial Data This section will show you how to take the data from the world borders shapefile and import it into GeoDjango models using the :ref:`ref-layermapping`. -There are many different different ways to import data in to a +There are many different different ways to import data in to a spatial database -- besides the tools included within GeoDjango, you may also use the following to populate your spatial database: -* `ogr2ogr`_: Command-line utility, included with GDAL, that +* `ogr2ogr`_: Command-line utility, included with GDAL, that supports loading a multitude of vector data formats into the PostGIS, MySQL, and Oracle spatial databases. * `shp2pgsql`_: This utility is included with PostGIS and only supports @@ -339,7 +339,7 @@ tutorial, then we can determine the path using Python's built-in >>> world_shp = os.path.abspath(os.path.join(os.path.dirname(world.__file__), ... 'data/TM_WORLD_BORDERS-0.3.shp')) -Now, the world borders shapefile may be opened using GeoDjango's +Now, the world borders shapefile may be opened using GeoDjango's :class:`~django.contrib.gis.gdal.DataSource` interface:: >>> from django.contrib.gis.gdal import * @@ -347,7 +347,7 @@ Now, the world borders shapefile may be opened using GeoDjango's >>> print ds / ... /geodjango/world/data/TM_WORLD_BORDERS-0.3.shp (ESRI Shapefile) -Data source objects can have different layers of geospatial features; however, +Data source objects can have different layers of geospatial features; however, shapefiles are only allowed to have one layer:: >>> print len(ds) @@ -367,10 +367,10 @@ contains:: .. note:: Unfortunately the shapefile data format does not allow for greater - specificity with regards to geometry types. This shapefile, like + specificity with regards to geometry types. This shapefile, like many others, actually includes ``MultiPolygon`` geometries in its features. You need to watch out for this when creating your models - as a GeoDjango ``PolygonField`` will not accept a ``MultiPolygon`` + as a GeoDjango ``PolygonField`` will not accept a ``MultiPolygon`` type geometry -- thus a ``MultiPolygonField`` is used in our model's definition instead. @@ -391,7 +391,7 @@ system associated with it -- if it does, the ``srs`` attribute will return a Here we've noticed that the shapefile is in the popular WGS84 spatial reference system -- in other words, the data uses units of degrees longitude and latitude. -In addition, shapefiles also support attribute fields that may contain +In addition, shapefiles also support attribute fields that may contain additional data. Here are the fields on the World Borders layer: >>> print lyr.fields @@ -403,8 +403,8 @@ a string) associated with each of the fields: >>> [fld.__name__ for fld in lyr.field_types] ['OFTString', 'OFTString', 'OFTString', 'OFTInteger', 'OFTString', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTReal', 'OFTReal'] -You can iterate over each feature in the layer and extract information from both -the feature's geometry (accessed via the ``geom`` attribute) as well as the +You can iterate over each feature in the layer and extract information from both +the feature's geometry (accessed via the ``geom`` attribute) as well as the feature's attribute fields (whose **values** are accessed via ``get()`` method):: @@ -427,7 +427,7 @@ And individual features may be retrieved by their feature ID:: >>> print feat.get('NAME') San Marino -Here the boundary geometry for San Marino is extracted and looking +Here the boundary geometry for San Marino is extracted and looking exported to WKT and GeoJSON:: >>> geom = feat.geom @@ -465,7 +465,7 @@ We're going to dive right in -- create a file called ``load.py`` inside the world_shp = os.path.abspath(os.path.join(os.path.dirname(__file__), 'data/TM_WORLD_BORDERS-0.3.shp')) def run(verbose=True): - lm = LayerMapping(WorldBorders, world_shp, world_mapping, + lm = LayerMapping(WorldBorders, world_shp, world_mapping, transform=False, encoding='iso-8859-1') lm.save(strict=True, verbose=verbose) @@ -473,8 +473,8 @@ We're going to dive right in -- create a file called ``load.py`` inside the A few notes about what's going on: * Each key in the ``world_mapping`` dictionary corresponds to a field in the - ``WorldBorders`` model, and the value is the name of the shapefile field - that data will be loaded from. + ``WorldBorders`` model, and the value is the name of the shapefile field + that data will be loaded from. * The key ``mpoly`` for the geometry field is ``MULTIPOLYGON``, the geometry type we wish to import as. Even if simple polygons are encountered in the shapefile they will automatically be converted into collections prior @@ -503,10 +503,10 @@ do the work:: Try ``ogrinspect`` ------------------ -Now that you've seen how to define geographic models and import data with the +Now that you've seen how to define geographic models and import data with the :ref:`ref-layermapping`, it's possible to further automate this process with use of the :djadmin:`ogrinspect` management command. The :djadmin:`ogrinspect` -command introspects a GDAL-supported vector data source (e.g., a shapefile) and +command introspects a GDAL-supported vector data source (e.g., a shapefile) and generates a model definition and ``LayerMapping`` dictionary automatically. The general usage of the command goes as follows:: @@ -525,13 +525,13 @@ and mapping dictionary created above, automatically:: A few notes about the command-line options given above: * The ``--srid=4326`` option sets the SRID for the geographic field. -* The ``--mapping`` option tells ``ogrinspect`` to also generate a +* The ``--mapping`` option tells ``ogrinspect`` to also generate a mapping dictionary for use with :class:`~django.contrib.gis.utils.LayerMapping`. * The ``--multi`` option is specified so that the geographic field is a :class:`~django.contrib.gis.db.models.MultiPolygonField` instead of just a :class:`~django.contrib.gis.db.models.PolygonField`. -The command produces the following output, which may be copied +The command produces the following output, which may be copied directly into the ``models.py`` of a GeoDjango application:: # This is an auto-generated Django model module created by ogrinspect. @@ -584,7 +584,7 @@ Now, define a point of interest [#]_:: >>> pnt_wkt = 'POINT(-95.3385 29.7245)' The ``pnt_wkt`` string represents the point at -95.3385 degrees longitude, -and 29.7245 degrees latitude. The geometry is in a format known as +and 29.7245 degrees latitude. The geometry is in a format known as Well Known Text (WKT), an open standard issued by the Open Geospatial Consortium (OGC). [#]_ Import the ``WorldBorders`` model, and perform a ``contains`` lookup using the ``pnt_wkt`` as the parameter:: @@ -611,7 +611,7 @@ available -- the :ref:`ref-gis-db-api` documentation has more. Automatic Spatial Transformations --------------------------------- -When querying the spatial database GeoDjango automatically transforms +When querying the spatial database GeoDjango automatically transforms geometries if they're in a different coordinate system. In the following example, the coordinate will be expressed in terms of `EPSG SRID 32140`__, a coordinate system specific to south Texas **only** and in units of @@ -634,26 +634,26 @@ of abstraction:: ('SELECT "world_worldborders"."id", "world_worldborders"."name", "world_worldborders"."area", "world_worldborders"."pop2005", "world_worldborders"."fips", "world_worldborders"."iso2", "world_worldborders"."iso3", "world_worldborders"."un", "world_worldborders"."region", - "world_worldborders"."subregion", "world_worldborders"."lon", "world_worldborders"."lat", - "world_worldborders"."mpoly" FROM "world_worldborders" + "world_worldborders"."subregion", "world_worldborders"."lon", "world_worldborders"."lat", + "world_worldborders"."mpoly" FROM "world_worldborders" WHERE ST_Intersects("world_worldborders"."mpoly", ST_Transform(%s, 4326))', (<django.contrib.gis.db.backend.postgis.adaptor.PostGISAdaptor object at 0x25641b0>,)) >>> qs # printing evaluates the queryset - [<WorldBorders: United States>] + [<WorldBorders: United States>] __ http://spatialreference.org/ref/epsg/32140/ Lazy Geometries --------------- Geometries come to GeoDjango in a standardized textual representation. Upon -access of the geometry field, GeoDjango creates a `GEOS geometry object <ref-geos>`, -exposing powerful functionality, such as serialization properties for +access of the geometry field, GeoDjango creates a `GEOS geometry object <ref-geos>`, +exposing powerful functionality, such as serialization properties for popular geospatial formats:: >>> sm = WorldBorders.objects.get(name='San Marino') >>> sm.mpoly <MultiPolygon object at 0x24c6798> - >>> sm.mpoly.wkt # WKT + >>> sm.mpoly.wkt # WKT MULTIPOLYGON (((12.4157980000000006 43.9579540000000009, 12.4505540000000003 43.9797209999999978, ... >>> sm.mpoly.wkb # WKB (as Python binary buffer) <read-only buffer for 0x1fe2c70, size -1, offset 0 at 0x2564c40> @@ -682,16 +682,16 @@ Google Geographic Admin ---------------- -GeoDjango extends :ref:`Django's admin application <ref-contrib-admin>` to -enable support for editing geometry fields. +GeoDjango extends :doc:`Django's admin application </ref/contrib/admin/index>` +to enable support for editing geometry fields. Basics ^^^^^^ -GeoDjango also supplements the Django admin by allowing users to create +GeoDjango also supplements the Django admin by allowing users to create and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_). -Let's dive in again -- create a file called ``admin.py`` inside the +Let's dive in again -- create a file called ``admin.py`` inside the ``world`` application, and insert the following:: from django.contrib.gis import admin diff --git a/docs/ref/contrib/humanize.txt b/docs/ref/contrib/humanize.txt index 07a62a7fbe..17db3c2535 100644 --- a/docs/ref/contrib/humanize.txt +++ b/docs/ref/contrib/humanize.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-humanize: - ======================== django.contrib.humanize ======================== diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index bb470e3041..90edf72c94 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-index: - ==================== ``contrib`` packages ==================== @@ -35,6 +33,7 @@ those packages have. gis/index humanize localflavor + markup messages redirects sitemaps @@ -46,8 +45,8 @@ admin ===== The automatic Django administrative interface. For more information, see -:ref:`Tutorial 2 <intro-tutorial02>` and the -:ref:`admin documentation <ref-contrib-admin>`. +:doc:`Tutorial 2 </intro/tutorial02>` and the +:doc:`admin documentation </ref/contrib/admin/index>`. Requires the auth_ and contenttypes_ contrib packages to be installed. @@ -56,16 +55,16 @@ auth Django's authentication framework. -See :ref:`topics-auth`. +See :doc:`/topics/auth`. comments ======== .. versionchanged:: 1.0 - The comments application has been rewriten. See :ref:`ref-contrib-comments-upgrade` + The comments application has been rewriten. See :doc:`/ref/contrib/comments/upgrade` for information on howto upgrade. -A simple yet flexible comments system. See :ref:`ref-contrib-comments-index`. +A simple yet flexible comments system. See :doc:`/ref/contrib/comments/index`. contenttypes ============ @@ -73,21 +72,21 @@ contenttypes A light framework for hooking into "types" of content, where each installed Django model is a separate content type. -See the :ref:`contenttypes documentation <ref-contrib-contenttypes>`. +See the :doc:`contenttypes documentation </ref/contrib/contenttypes>`. csrf ==== A middleware for preventing Cross Site Request Forgeries -See the :ref:`csrf documentation <ref-contrib-csrf>`. +See the :doc:`csrf documentation </ref/contrib/csrf>`. flatpages ========= A framework for managing simple "flat" HTML content in a database. -See the :ref:`flatpages documentation <ref-contrib-flatpages>`. +See the :doc:`flatpages documentation </ref/contrib/flatpages>`. Requires the sites_ contrib package to be installed as well. @@ -103,14 +102,14 @@ An abstraction of the following workflow: "Display an HTML form, force a preview, then do something with the submission." -See the :ref:`form preview documentation <ref-contrib-formtools-form-preview>`. +See the :doc:`form preview documentation </ref/contrib/formtools/form-preview>`. django.contrib.formtools.wizard -------------------------------- Splits forms across multiple Web pages. -See the :ref:`form wizard documentation <ref-contrib-formtools-form-wizard>`. +See the :doc:`form wizard documentation </ref/contrib/formtools/form-wizard>`. gis ==== @@ -118,14 +117,14 @@ gis A world-class geospatial framework built on top of Django, that enables storage, manipulation and display of spatial data. -See the :ref:`ref-contrib-gis` documentation for more. +See the :doc:`/ref/contrib/gis/index` documentation for more. humanize ======== A set of Django template filters useful for adding a "human touch" to data. -See the :ref:`humanize documentation <ref-contrib-humanize>`. +See the :doc:`humanize documentation </ref/contrib/humanize>`. localflavor =========== @@ -134,45 +133,14 @@ A collection of various Django snippets that are useful only for a particular country or culture. For example, ``django.contrib.localflavor.us.forms`` contains a ``USZipCodeField`` that you can use to validate U.S. zip codes. -See the :ref:`localflavor documentation <ref-contrib-localflavor>`. - -.. _ref-contrib-markup: +See the :doc:`localflavor documentation </ref/contrib/localflavor>`. markup ====== -A collection of template filters that implement common markup languages: - - * ``textile`` -- implements `Textile`_ -- requires `PyTextile`_ - * ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ - * ``restructuredtext`` -- implements `ReST (ReStructured Text)`_ - -- requires `doc-utils`_ - -In each case, the filter expects formatted markup as a string and returns a -string representing the marked-up text. For example, the ``textile`` filter -converts text that is marked-up in Textile format to HTML. - -To activate these filters, add ``'django.contrib.markup'`` to your -:setting:`INSTALLED_APPS` setting. Once you've done that, use -``{% load markup %}`` in a template, and you'll have access to these filters. -For more documentation, read the source code in -:file:`django/contrib/markup/templatetags/markup.py`. - -.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 -.. _Markdown: http://en.wikipedia.org/wiki/Markdown -.. _ReST (ReStructured Text): http://en.wikipedia.org/wiki/ReStructuredText -.. _PyTextile: http://loopcore.com/python-textile/ -.. _Python-markdown: http://www.freewisdom.org/projects/python-markdown -.. _doc-utils: http://docutils.sf.net/ - -ReStructured Text ------------------ - -When using the `restructuredtext` markup filter you can define a :setting:`RESTRUCTUREDTEXT_FORMAT_SETTINGS` -in your django settings to override the default writer settings. See the `restructuredtext writer settings`_ for -details on what these settings are. +A collection of template filters that implement common markup languages -.. _restructuredtext writer settings: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer +See the :doc:`markup documentation </ref/contrib/markup>`. messages ======== @@ -183,21 +151,21 @@ messages A framework for storing and retrieving temporary cookie- or session-based messages -See the :ref:`messages documentation <ref-contrib-messages>`. +See the :doc:`messages documentation </ref/contrib/messages>`. redirects ========= A framework for managing redirects. -See the :ref:`redirects documentation <ref-contrib-redirects>`. +See the :doc:`redirects documentation </ref/contrib/redirects>`. sessions ======== A framework for storing data in anonymous sessions. -See the :ref:`sessions documentation <topics-http-sessions>`. +See the :doc:`sessions documentation </topics/http/sessions>`. sites ===== @@ -206,21 +174,21 @@ 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 :ref:`sites documentation <ref-contrib-sites>`. +See the :doc:`sites documentation </ref/contrib/sites>`. sitemaps ======== A framework for generating Google sitemap XML files. -See the :ref:`sitemaps documentation <ref-contrib-sitemaps>`. +See the :doc:`sitemaps documentation </ref/contrib/sitemaps>`. syndication =========== A framework for generating syndication feeds, in RSS and Atom, quite easily. -See the :ref:`syndication documentation <ref-contrib-syndication>`. +See the :doc:`syndication documentation </ref/contrib/syndication>`. webdesign ========= @@ -228,7 +196,7 @@ webdesign Helpers and utilities targeted primarily at Web *designers* rather than Web *developers*. -See the :ref:`Web design helpers documentation <ref-contrib-webdesign>`. +See the :doc:`Web design helpers documentation </ref/contrib/webdesign>`. Other add-ons ============= diff --git a/docs/ref/contrib/localflavor.txt b/docs/ref/contrib/localflavor.txt index 1c58e2d5e8..48cfa6340a 100644 --- a/docs/ref/contrib/localflavor.txt +++ b/docs/ref/contrib/localflavor.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-localflavor: - ========================== The "local flavor" add-ons ========================== @@ -17,7 +15,7 @@ Inside that package, country- or culture-specific code is organized into subpackages, named using `ISO 3166 country codes`_. Most of the ``localflavor`` add-ons are localized form components deriving -from the :ref:`forms <topics-forms-index>` framework -- for example, a +from the :doc:`forms </topics/forms/index>` framework -- for example, a :class:`~django.contrib.localflavor.us.forms.USStateField` that knows how to validate U.S. state abbreviations, and a :class:`~django.contrib.localflavor.fi.forms.FISocialSecurityNumber` that @@ -74,7 +72,7 @@ Countries currently supported by :mod:`~django.contrib.localflavor` are: The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage, containing useful code that is not specific to one particular country or culture. Currently, it defines date, datetime and split datetime input fields based on -those from :ref:`forms <topics-forms-index>`, but with non-US default formats. +those from :doc:`forms </topics/forms/index>`, but with non-US default formats. Here's an example of how to use them:: from django import forms diff --git a/docs/ref/contrib/markup.txt b/docs/ref/contrib/markup.txt new file mode 100644 index 0000000000..f2c43fe25f --- /dev/null +++ b/docs/ref/contrib/markup.txt @@ -0,0 +1,42 @@ +===================== +django.contrib.markup +===================== + +.. module:: django.contrib.markup + :synopsis: A collection of template filters that implement common markup languages. + +Django provides template filters that implement the following markup +languages: + + * ``textile`` -- implements `Textile`_ -- requires `PyTextile`_ + * ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ + * ``restructuredtext`` -- implements `ReST (ReStructured Text)`_ + -- requires `doc-utils`_ + +In each case, the filter expects formatted markup as a string and +returns a string representing the marked-up text. For example, the +``textile`` filter converts text that is marked-up in Textile format +to HTML. + +To activate these filters, add ``'django.contrib.markup'`` to your +:setting:`INSTALLED_APPS` setting. Once you've done that, use +``{% load markup %}`` in a template, and you'll have access to these filters. +For more documentation, read the source code in +:file:`django/contrib/markup/templatetags/markup.py`. + +.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 +.. _Markdown: http://en.wikipedia.org/wiki/Markdown +.. _ReST (ReStructured Text): http://en.wikipedia.org/wiki/ReStructuredText +.. _PyTextile: http://loopcore.com/python-textile/ +.. _Python-markdown: http://www.freewisdom.org/projects/python-markdown +.. _doc-utils: http://docutils.sf.net/ + +ReStructured Text +----------------- + +When using the ``restructuredtext`` markup filter you can define a +:setting:`RESTRUCTUREDTEXT_FILTER_SETTINGS` in your django settings to +override the default writer settings. See the `restructuredtext writer +settings`_ for details on what these settings are. + +.. _restructuredtext writer settings: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt index 554e70b1f2..3081f2718d 100644 --- a/docs/ref/contrib/messages.txt +++ b/docs/ref/contrib/messages.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-messages: - ====================== The messages framework ====================== @@ -20,8 +18,8 @@ with a specific ``level`` that determines its priority (e.g., ``info``, Enabling messages ================= -Messages are implemented through a :ref:`middleware <ref-middleware>` -class and corresponding :ref:`context processor <ref-templates-api>`. +Messages are implemented through a :doc:`middleware </ref/middleware>` +class and corresponding :doc:`context processor </ref/templates/api>`. To enable message functionality, do the following: @@ -29,7 +27,7 @@ To enable message functionality, do the following: it contains ``'django.contrib.messages.middleware.MessageMiddleware'``. If you are using a :ref:`storage backend <message-storage-backends>` that - relies on :ref:`sessions <topics-http-sessions>` (the default), + relies on :doc:`sessions </topics/http/sessions>` (the default), ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be enabled and appear before ``MessageMiddleware`` in your :setting:`MIDDLEWARE_CLASSES`. @@ -106,7 +104,7 @@ LegacyFallbackStorage The ``LegacyFallbackStorage`` is a temporary tool to facilitate the transition from the deprecated ``user.message_set`` API and will be removed in Django 1.4 according to Django's standard deprecation policy. For more information, see -the full :ref:`release process documentation <internals-release-process>`. +the full :doc:`release process documentation </internals/release-process>`. In addition to the functionality in the ``FallbackStorage``, it adds a custom, read-only storage class that retrieves messages from the user ``Message`` @@ -300,7 +298,7 @@ example:: messages.info(request, 'Hello world.', fail_silently=True) Internally, Django uses this functionality in the create, update, and delete -:ref:`generic views <topics-generic-views>` so that they work even if the +:doc:`generic views </topics/http/generic-views>` so that they work even if the message framework is disabled. .. note:: @@ -343,7 +341,7 @@ window/tab will have its own browsing context. Settings ======== -A few :ref:`Django settings <ref-settings>` give you control over message +A few :doc:`Django settings </ref/settings>` give you control over message behavior: MESSAGE_LEVEL diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index 6f9c57c09d..f1a58cb207 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-redirects: - ================= The redirects app ================= @@ -47,8 +45,8 @@ Note that the order of :setting:`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 :ref:`middleware docs -<topics-http-middleware>`. +For more on middleware, read the :doc:`middleware docs +</topics/http/middleware>`. How to add, change and delete redirects ======================================= @@ -65,8 +63,8 @@ Via the Python API .. class:: models.Redirect - Redirects are represented by a standard :ref:`Django model <topics-db-models>`, + Redirects are represented by a standard :doc:`Django model </topics/db/models>`, which lives in `django/contrib/redirects/models.py`_. You can access redirect - objects via the :ref:`Django database API <topics-db-queries>`. + objects via the :doc:`Django database API </topics/db/queries>`. .. _django/contrib/redirects/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models.py diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index a71f19d786..7a66cbe9a9 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-sitemaps: - ===================== The sitemap framework ===================== @@ -23,10 +21,10 @@ site. The Django sitemap framework automates the creation of this XML file by letting you express this information in Python code. -It works much like Django's :ref:`syndication framework -<ref-contrib-syndication>`. To create a sitemap, just write a +It works much like Django's :doc:`syndication framework +</ref/contrib/syndication>`. To create a sitemap, just write a :class:`~django.contrib.sitemaps.Sitemap` class and point to it in your -:ref:`URLconf <topics-http-urls>`. +:doc:`URLconf </topics/http/urls>`. Installation ============ @@ -52,7 +50,7 @@ Initialization ============== To activate sitemap generation on your Django site, add this line to your -:ref:`URLconf <topics-http-urls>`:: +:doc:`URLconf </topics/http/urls>`:: (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps}) @@ -217,8 +215,8 @@ The sitemap framework provides a couple convenience classes for common cases: .. class:: FlatPageSitemap The :class:`django.contrib.sitemaps.FlatPageSitemap` class looks at all - :mod:`flatpages <django.contrib.flatpages>` defined for the current - :setting:`SITE_ID` (see the + publicly visible :mod:`flatpages <django.contrib.flatpages>` + defined for the current :setting:`SITE_ID` (see the :mod:`sites documentation <django.contrib.sites>`) and creates an entry in the sitemap. These entries include only the :attr:`~Sitemap.location` attribute -- not :attr:`~Sitemap.lastmod`, @@ -227,7 +225,7 @@ The sitemap framework provides a couple convenience classes for common cases: .. class:: GenericSitemap The :class:`django.contrib.sitemaps.GenericSitemap` class works with any - :ref:`generic views <ref-generic-views>` you already have. + :doc:`generic views </ref/generic-views>` you already have. To use it, create an instance, passing in the same :data:`info_dict` you pass to the generic views. The only requirement is that the dictionary have a :data:`queryset` entry. It may also have a :data:`date_field` entry that specifies a @@ -240,7 +238,7 @@ The sitemap framework provides a couple convenience classes for common cases: Example ------- -Here's an example of a :ref:`URLconf <topics-http-urls>` using both:: +Here's an example of a :doc:`URLconf </topics/http/urls>` using both:: from django.conf.urls.defaults import * from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index b7cb8d6a58..7ff05a5c82 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-sites: - ===================== The "sites" framework ===================== @@ -104,6 +102,8 @@ like this:: This has the same benefits as described in the last section. +.. _hooking-into-current-site-from-views: + Hooking into the current site from views ---------------------------------------- @@ -260,7 +260,7 @@ The ``CurrentSiteManager`` If :class:`~django.contrib.sites.models.Site` plays a key role in your application, consider using the helpful :class:`~django.contrib.sites.managers.CurrentSiteManager` in your -model(s). It's a model :ref:`manager <topics-db-managers>` that +model(s). It's a model :doc:`manager </topics/db/managers>` that automatically filters its queries to include only objects associated with the current :class:`~django.contrib.sites.models.Site`. @@ -322,7 +322,7 @@ and pass a field name that doesn't exist, Django will raise a :exc:`ValueError`. Finally, note that you'll probably want to keep a normal (non-site-specific) ``Manager`` on your model, even if you use :class:`~django.contrib.sites.managers.CurrentSiteManager`. As -explained in the :ref:`manager documentation <topics-db-managers>`, if +explained in the :doc:`manager documentation </topics/db/managers>`, if you define a manager manually, then Django won't create the automatic ``objects = models.Manager()`` manager for you. Also note that certain parts of Django -- namely, the Django admin site and generic views -- @@ -387,7 +387,7 @@ Here's how Django uses the sites framework: .. versionadded:: 1.0 -Some :ref:`django.contrib <ref-contrib-index>` applications take advantage of +Some :doc:`django.contrib </ref/contrib/index>` applications take advantage of the sites framework but are architected in a way that doesn't *require* the sites framework to be installed in your database. (Some people don't want to, or just aren't *able* to install the extra database table that the sites framework diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index 7b47ef8a4e..a12d646a08 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-syndication: - ============================== The syndication feed framework ============================== @@ -38,8 +36,8 @@ Overview The high-level feed-generating framework is supplied by the :class:`~django.contrib.syndication.views.Feed` class. To create a feed, write a :class:`~django.contrib.syndication.views.Feed` class -and point to an instance of it in your :ref:`URLconf -<topics-http-urls>`. +and point to an instance of it in your :doc:`URLconf +</topics/http/urls>`. Feed classes ------------ @@ -54,7 +52,7 @@ Feed classes subclass :class:`django.contrib.syndication.views.Feed`. They can live anywhere in your codebase. Instances of :class:`~django.contrib.syndication.views.Feed` classes -are views which can be used in your :ref:`URLconf <topics-http-urls>`. +are views which can be used in your :doc:`URLconf </topics/http/urls>`. A simple example ---------------- @@ -80,7 +78,7 @@ latest five news items:: return item.description To connect a URL to this feed, put an instance of the Feed object in -your :ref:`URLconf <topics-http-urls>`. For example:: +your :doc:`URLconf </topics/http/urls>`. For example:: from django.conf.urls.defaults import * from myproject.feeds import LatestEntriesFeed @@ -102,7 +100,7 @@ Note: * :meth:`items()` is, simply, a method that returns a list of objects that should be included in the feed as ``<item>`` elements. Although this example returns ``NewsItem`` objects using Django's - :ref:`object-relational mapper <ref-models-querysets>`, :meth:`items()` + :doc:`object-relational mapper </ref/models/querysets>`, :meth:`items()` doesn't have to return model instances. Although you get a few bits of functionality "for free" by using Django models, :meth:`items()` can return any type of object you want. @@ -123,7 +121,7 @@ into those elements. both. If you want to do any special formatting for either the title or - description, :ref:`Django templates <topics-templates>` can be used + description, :doc:`Django templates </topics/templates>` can be used instead. Their paths can be specified with the ``title_template`` and ``description_template`` attributes on the :class:`~django.contrib.syndication.views.Feed` class. The templates are @@ -167,7 +165,7 @@ police beat in Chicago. It'd be silly to create a separate :class:`~django.contrib.syndication.views.Feed` class for each police beat; that would violate the :ref:`DRY principle <dry>` and would couple data to programming logic. Instead, the syndication framework lets you access the -arguments passed from your :ref:`URLconf <topics-http-urls>` so feeds can output +arguments passed from your :doc:`URLconf </topics/http/urls>` so feeds can output items based on information in the feed's URL. On chicagocrime.org, the police-beat feeds are accessible via URLs like this: @@ -175,7 +173,7 @@ On chicagocrime.org, the police-beat feeds are accessible via URLs like this: * :file:`/beats/613/rss/` -- Returns recent crimes for beat 613. * :file:`/beats/1424/rss/` -- Returns recent crimes for beat 1424. -These can be matched with a :ref:`URLconf <topics-http-urls>` line such as:: +These can be matched with a :doc:`URLconf </topics/http/urls>` line such as:: (r'^beats/(?P<beat_id>\d+)/rss/$', BeatFeed()), diff --git a/docs/ref/contrib/webdesign.txt b/docs/ref/contrib/webdesign.txt index e69ad49232..d355d03565 100644 --- a/docs/ref/contrib/webdesign.txt +++ b/docs/ref/contrib/webdesign.txt @@ -1,5 +1,3 @@ -.. _ref-contrib-webdesign: - ======================== django.contrib.webdesign ======================== @@ -9,13 +7,13 @@ django.contrib.webdesign rather than Web *developers*. The ``django.contrib.webdesign`` package, part of the -:ref:`"django.contrib" add-ons <ref-contrib-index>`, provides various Django +:doc:`"django.contrib" add-ons </ref/contrib/index>`, provides various Django helpers that are particularly useful to Web *designers* (as opposed to developers). At present, the package contains only a single template tag. If you have ideas for Web-designer-friendly functionality in Django, please -:ref:`suggest them <internals-contributing>`. +:doc:`suggest them </internals/contributing>`. Template tags ============= |