Author: julien
Date: 2011-09-28 07:00:43 -0700 (Wed, 28 Sep 2011)
New Revision: 16911
Modified:
django/trunk/docs/ref/contrib/gis/tutorial.txt
Log:
Fixed #16949 -- Fixed a small typo in the GIS tutorial and also made some minor
PEP8 fixes and added some code-block directives while I was at it. Thanks to
jgomo3 for the report.
Modified: django/trunk/docs/ref/contrib/gis/tutorial.txt
===================================================================
--- django/trunk/docs/ref/contrib/gis/tutorial.txt 2011-09-28 02:26:12 UTC
(rev 16910)
+++ django/trunk/docs/ref/contrib/gis/tutorial.txt 2011-09-28 14:00:43 UTC
(rev 16911)
@@ -7,7 +7,8 @@
GeoDjango is an add-on for Django that turns it into a world-class geographic
Web framework. GeoDjango strives to make it as simple as possible to create
-geographic Web applications, like location-based services. Some features
include:
+geographic Web applications, like location-based services. Some features
+include:
* Django model fields for `OGC`_ geometries.
* Extensions to Django's ORM for the querying and manipulation of spatial data.
@@ -16,8 +17,8 @@
* 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 :doc:`regular tutorial </intro/tutorial01>` to
introduce
-yourself with basic Django concepts.
+Django please read through the :doc:`regular tutorial </intro/tutorial01>` to
+introduce yourself with basic Django concepts.
.. note::
@@ -52,16 +53,21 @@
First, a spatial database needs to be created for our project. If using
PostgreSQL and PostGIS, then the following commands will
-create the database from a :ref:`spatial database template
<spatialdb_template>`::
+create the database from a :ref:`spatial database template
+<spatialdb_template>`:
+.. code-block:: bash
+
$ createdb -T template_postgis geodjango
.. note::
This command must be issued by a database user that has permissions to
create a database. Here is an example set of commands to create such
- a user::
+ a user:
+ .. code-block:: bash
+
$ sudo su - postgres
$ createuser --createdb geo
$ exit
@@ -76,20 +82,25 @@
Create GeoDjango Project
------------------------
-Use the ``django-admin.py`` script like normal to create a ``geodjango``
project::
+Use the ``django-admin.py`` script like normal to create a ``geodjango``
+project:
+.. code-block:: bash
+
$ django-admin.py startproject geodjango
With the project initialized, now create a ``world`` Django application within
-the ``geodjango`` project::
+the ``geodjango`` project:
+.. code-block:: bash
+
$ cd geodjango
$ python manage.py startapp world
Configure ``settings.py``
-------------------------
-The ``geodjango`` project settings are stored in the ``settings.py`` file.
Edit
+The ``geodjango`` project settings are stored in the ``settings.py`` file. Edit
the database connection settings appropriately::
DATABASES = {
@@ -126,10 +137,12 @@
World Borders
-------------
-The world borders data is available in this `zip file`__. Create a data
directory
-in the ``world`` application, download the world borders data, and unzip.
-On GNU/Linux platforms the following commands should do it::
+The world borders data is available in this `zip file`__. Create a data
+directory in the ``world`` application, download the world borders data, and
+unzip. On GNU/Linux platforms the following commands should do it:
+.. code-block:: bash
+
$ mkdir world/data
$ cd world/data
$ wget http://thematicmapping.org/downloads/TM_WORLD_BORDERS-0.3.zip
@@ -138,7 +151,8 @@
The world borders ZIP file contains a set of data files collectively known as
an `ESRI Shapefile`__, one of the most popular geospatial data formats. When
-unzipped the world borders data set includes files with the following
extensions:
+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``.
@@ -154,8 +168,10 @@
---------------------------------------
The GDAL ``ogrinfo`` utility is excellent for examining metadata about
-shapefiles (or other vector data sources)::
+shapefiles (or other vector data sources):
+.. code-block:: bash
+
$ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp
INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
using driver `ESRI Shapefile' successful.
@@ -163,8 +179,10 @@
Here ``ogrinfo`` is telling us that the shapefile has one layer, and that
layer contains polygon data. To find out more we'll specify the layer name
-and use the ``-so`` option to get only important summary information::
+and use the ``-so`` option to get only important summary information:
+.. code-block:: bash
+
$ ogrinfo -so world/data/TM_WORLD_BORDERS-0.3.shp TM_WORLD_BORDERS-0.3
INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
using driver `ESRI Shapefile' successful.
@@ -197,8 +215,8 @@
``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`_ Web site, this
shows
-you how to determine this information yourself when such metadata is not
+this information may be found right on the `world borders`_ Web site, this
+shows you how to determine this information yourself when such metadata is not
provided.
Geographic Models
@@ -243,25 +261,28 @@
:class:`~django.contrib.gis.db.models.GeoManager`; this is *required*
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.
+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.
__ http://en.wikipedia.org/wiki/SRID
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
``WorldBorder``
-model::
+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
+``WorldBorder`` model::
$ python manage.py sqlall world
-This management command should produce the following output::
+This management command should produce the following output:
+.. code-block:: sql
+
BEGIN;
CREATE TABLE "world_worldborders" (
"id" serial NOT NULL PRIMARY KEY,
@@ -290,18 +311,19 @@
Creating table world_worldborders
Installing custom SQL for world.WorldBorder 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
+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
``createsuperuser`` management command).
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
-spatial database -- besides the tools included within GeoDjango, you
-may also use the following to populate your spatial database:
+shapefile and import it into GeoDjango models using the
+:ref:`ref-layermapping`.
+There are many 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
supports loading a multitude of vector data formats into
@@ -322,8 +344,10 @@
library -- in other words, you'll be able explore all the vector data sources
that OGR supports via a Pythonic API.
-First, invoke the Django shell::
+First, invoke the Django shell:
+.. code-block:: bash
+
$ python manage.py shell
If the :ref:`worldborders` data was downloaded like earlier in the
@@ -385,7 +409,8 @@
'+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
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.
+system -- in other words, the data uses units of degrees longitude and
+latitude.
In addition, shapefiles also support attribute fields that may contain
additional data. Here are the fields on the World Borders layer:
@@ -484,8 +509,10 @@
the shapefile. This ensures that string values are read and saved correctly
from their original encoding system.
-Afterwards, invoke the Django shell from the ``geodjango`` project directory::
+Afterwards, invoke the Django shell from the ``geodjango`` project directory:
+.. code-block:: bash
+
$ python manage.py shell
Next, import the ``load`` module, call the ``run`` routine, and watch
``LayerMapping``
@@ -502,11 +529,13 @@
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
-generates a model definition and ``LayerMapping`` dictionary automatically.
+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::
+The general usage of the command goes as follows:
+.. code-block:: bash
+
$ python manage.py ogrinspect [options] <data_source> <model_name>
[options]
Where ``data_source`` is the path to the GDAL-supported data source and
@@ -514,15 +543,18 @@
be used to further define how the model is generated.
For example, the following command nearly reproduces the ``WorldBorder`` model
-and mapping dictionary created above, automatically::
+and mapping dictionary created above, automatically:
+.. code-block:: bash
+
$ python manage.py ogrinspect world/data/TM_WORLD_BORDERS-0.3.shp
WorldBorder --srid=4326 --mapping --multi
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
- mapping dictionary for use with
:class:`~django.contrib.gis.utils.LayerMapping`.
+ 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`.
@@ -571,8 +603,10 @@
---------------
GeoDjango extends the Django ORM and allows the use of spatial lookups.
Let's do an example where we find the ``WorldBorder`` model that contains
-a point. First, fire up the management shell::
+a point. First, fire up the management shell:
+.. code-block:: bash
+
$ python manage.py shell
Now, define a point of interest [#]_::
@@ -592,8 +626,8 @@
Here we retrieved a ``GeoQuerySet`` that has only one model: the one
for the United States (which is what we would expect). Similarly,
-a :ref:`GEOS geometry object <ref-geos>` may also be used -- here the
``intersects``
-spatial lookup is combined with the ``get`` method to retrieve
+a :ref:`GEOS geometry object <ref-geos>` may also be used -- here the
+``intersects`` spatial lookup is combined with the ``get`` method to retrieve
only the ``WorldBorder`` instance for San Marino instead of a queryset::
>>> from django.contrib.gis.geos import Point
@@ -641,9 +675,9 @@
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
-popular geospatial formats::
+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 = WorldBorder.objects.get(name='San Marino')
>>> sm.mpoly
@@ -706,8 +740,10 @@
(r'^admin/', include(admin.site.urls)),
)
-Start up the Django development server::
+Start up the Django development server:
+.. code-block:: bash
+
$ python manage.py runserver
Finally, browse to ``http://localhost:8000/admin/``, and log in with the admin
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
