Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

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.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16911 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 804e32fae0a7bfa6520c157888c5c5f6a77f6206 1 parent c340f6a
@jphalip jphalip authored
Showing with 82 additions and 46 deletions.
  1. +82 −46 docs/ref/contrib/gis/tutorial.txt
View
128 docs/ref/contrib/gis/tutorial.txt
@@ -7,7 +7,8 @@ Introduction
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 @@ geographic Web applications, like location-based services. Some features includ
* 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,7 +53,10 @@ Create a Spatial Database
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
@@ -60,7 +64,9 @@ create the database from a :ref:`spatial database template <spatialdb_template>`
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
@@ -76,12 +82,17 @@ to create a :ref:`SpatiaLite database <create_spatialite_db>`.
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
@@ -89,7 +100,7 @@ the ``geodjango`` project::
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,9 +137,11 @@ Geographic Data
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
@@ -138,7 +151,8 @@ On GNU/Linux platforms the following commands should do it::
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,7 +168,9 @@ Use ``ogrinfo`` to examine spatial data
---------------------------------------
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'
@@ -163,7 +179,9 @@ shapefiles (or other vector data sources)::
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'
@@ -197,8 +215,8 @@ 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`_ 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,24 +261,27 @@ Two important things to note:
: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" (
@@ -290,18 +311,19 @@ If satisfied, you may then create this table in the database by running the
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,7 +344,9 @@ shapefile. Included within GeoDjango is an interface to GDAL's powerful OGR
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
@@ -385,7 +409,8 @@ system associated with it -- if it does, the ``srs`` attribute will return a
'+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,7 +509,9 @@ A few notes about what's going on:
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
@@ -502,10 +529,12 @@ Try ``ogrinspect``
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]
@@ -514,7 +543,9 @@ Where ``data_source`` is the path to the GDAL-supported data source and
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
@@ -522,7 +553,8 @@ 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,7 +603,9 @@ Spatial Lookups
---------------
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
@@ -592,8 +626,8 @@ a ``contains`` lookup using the ``pnt_wkt`` as the parameter::
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 @@ __ 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
-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,7 +740,9 @@ as follows::
(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
Please sign in to comment.
Something went wrong with that request. Please try again.