Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
Julien Phalip authored September 28, 2011

Showing 1 changed file with 82 additions and 46 deletions. Show diff stats Hide diff stats

  1. 128  docs/ref/contrib/gis/tutorial.txt
128  docs/ref/contrib/gis/tutorial.txt
@@ -7,7 +7,8 @@ Introduction
7 7
 
8 8
 GeoDjango is an add-on for Django that turns it into a world-class geographic
9 9
 Web framework.  GeoDjango strives to make it as simple as possible to create
10  
-geographic Web applications, like location-based services.  Some features include:
  10
+geographic Web applications, like location-based services.  Some features
  11
+include:
11 12
 
12 13
 * Django model fields for `OGC`_ geometries.
13 14
 * 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
16 17
 * Editing of geometry fields inside the admin.
17 18
 
18 19
 This tutorial assumes a familiarity with Django; thus, if you're brand new to
19  
-Django please read through the :doc:`regular tutorial </intro/tutorial01>` to introduce
20  
-yourself with basic Django concepts.
  20
+Django please read through the :doc:`regular tutorial </intro/tutorial01>` to
  21
+introduce yourself with basic Django concepts.
21 22
 
22 23
 .. note::
23 24
 
@@ -52,7 +53,10 @@ Create a Spatial Database
52 53
 
53 54
 First, a spatial database needs to be created for our project.  If using
54 55
 PostgreSQL and PostGIS, then the following commands will
55  
-create the database from a :ref:`spatial database template <spatialdb_template>`::
  56
+create the database from a :ref:`spatial database template
  57
+<spatialdb_template>`:
  58
+
  59
+.. code-block:: bash
56 60
 
57 61
     $ createdb -T template_postgis geodjango
58 62
 
@@ -60,7 +64,9 @@ create the database from a :ref:`spatial database template <spatialdb_template>`
60 64
 
61 65
     This command must be issued by a database user that has permissions to
62 66
     create a database.  Here is an example set of commands to create such
63  
-    a user::
  67
+    a user:
  68
+
  69
+    .. code-block:: bash
64 70
 
65 71
         $ sudo su - postgres
66 72
         $ createuser --createdb geo
@@ -76,12 +82,17 @@ to create a :ref:`SpatiaLite database <create_spatialite_db>`.
76 82
 Create GeoDjango Project
77 83
 ------------------------
78 84
 
79  
-Use the ``django-admin.py`` script like normal to create a ``geodjango`` project::
  85
+Use the ``django-admin.py`` script like normal to create a ``geodjango``
  86
+project:
  87
+
  88
+.. code-block:: bash
80 89
 
81 90
     $ django-admin.py startproject geodjango
82 91
 
83 92
 With the project initialized, now create a ``world`` Django application within
84  
-the ``geodjango`` project::
  93
+the ``geodjango`` project:
  94
+
  95
+.. code-block:: bash
85 96
 
86 97
     $ cd geodjango
87 98
     $ python manage.py startapp world
@@ -89,7 +100,7 @@ the ``geodjango`` project::
89 100
 Configure ``settings.py``
90 101
 -------------------------
91 102
 
92  
-The ``geodjango`` project settings are stored in the ``settings.py`` file.  Edit
  103
+The ``geodjango`` project settings are stored in the ``settings.py`` file. Edit
93 104
 the database connection settings appropriately::
94 105
 
95 106
     DATABASES = {
@@ -126,9 +137,11 @@ Geographic Data
126 137
 World Borders
127 138
 -------------
128 139
 
129  
-The world borders data is available in this `zip file`__.  Create a data directory
130  
-in the ``world`` application, download the world borders data, and unzip.
131  
-On GNU/Linux platforms the following commands should do it::
  140
+The world borders data is available in this `zip file`__.  Create a data
  141
+directory in the ``world`` application, download the world borders data, and
  142
+unzip. On GNU/Linux platforms the following commands should do it:
  143
+
  144
+.. code-block:: bash
132 145
 
133 146
     $ mkdir world/data
134 147
     $ cd world/data
@@ -138,7 +151,8 @@ On GNU/Linux platforms the following commands should do it::
138 151
 
139 152
 The world borders ZIP file contains a set of data files collectively known as
140 153
 an `ESRI Shapefile`__, one of the most popular geospatial data formats.  When
141  
-unzipped the world borders data set includes files with the following extensions:
  154
+unzipped the world borders data set includes files with the following
  155
+extensions:
142 156
 
143 157
 * ``.shp``: Holds the vector data for the world borders geometries.
144 158
 * ``.shx``: Spatial index file for geometries stored in the ``.shp``.
@@ -154,7 +168,9 @@ Use ``ogrinfo`` to examine spatial data
154 168
 ---------------------------------------
155 169
 
156 170
 The GDAL ``ogrinfo`` utility is excellent for examining metadata about
157  
-shapefiles (or other vector data sources)::
  171
+shapefiles (or other vector data sources):
  172
+
  173
+.. code-block:: bash
158 174
 
159 175
     $ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp
160 176
     INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
@@ -163,7 +179,9 @@ shapefiles (or other vector data sources)::
163 179
 
164 180
 Here ``ogrinfo`` is telling us that the shapefile has one layer, and that
165 181
 layer contains polygon data.  To find out more we'll specify the layer name
166  
-and use the ``-so`` option to get only important summary information::
  182
+and use the ``-so`` option to get only important summary information:
  183
+
  184
+.. code-block:: bash
167 185
 
168 186
     $ ogrinfo -so world/data/TM_WORLD_BORDERS-0.3.shp TM_WORLD_BORDERS-0.3
169 187
     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,
197 215
 ``FIPS: String (2.0)`` indicates that there's a ``FIPS`` character field
198 216
 with a maximum length of 2; similarly, ``LON: Real (8.3)`` is a floating-point
199 217
 field that holds a maximum of 8 digits up to three decimal places.  Although
200  
-this information may be found right on the `world borders`_ Web site, this shows
201  
-you how to determine this information yourself when such metadata is not
  218
+this information may be found right on the `world borders`_ Web site, this
  219
+shows you how to determine this information yourself when such metadata is not
202 220
 provided.
203 221
 
204 222
 Geographic Models
@@ -243,24 +261,27 @@ Two important things to note:
243 261
    :class:`~django.contrib.gis.db.models.GeoManager`; this is *required*
244 262
    to perform spatial queries.
245 263
 
246  
-When declaring a geometry field on your model the default spatial reference system
247  
-is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field coordinates are in
248  
-longitude/latitude pairs in units of degrees.  If you want the coordinate system to be
249  
-different, then SRID of the geometry field may be customized by setting the ``srid``
250  
-with an integer corresponding to the coordinate system of your choice.
  264
+When declaring a geometry field on your model the default spatial reference
  265
+system is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field
  266
+coordinates are in longitude/latitude pairs in units of degrees.  If you want
  267
+the coordinate system to be different, then SRID of the geometry field may be
  268
+customized by setting the ``srid`` with an integer corresponding to the
  269
+coordinate system of your choice.
251 270
 
252 271
 __ http://en.wikipedia.org/wiki/SRID
253 272
 
254 273
 Run ``syncdb``
255 274
 --------------
256 275
 
257  
-After you've defined your model, it needs to be synced with the spatial database.
258  
-First, let's look at the SQL that will generate the table for the ``WorldBorder``
259  
-model::
  276
+After you've defined your model, it needs to be synced with the spatial
  277
+database. First, let's look at the SQL that will generate the table for the
  278
+``WorldBorder`` model::
260 279
 
261 280
     $ python manage.py sqlall world
262 281
 
263  
-This management command should produce the following output::
  282
+This management command should produce the following output:
  283
+
  284
+.. code-block:: sql
264 285
 
265 286
     BEGIN;
266 287
     CREATE TABLE "world_worldborders" (
@@ -290,18 +311,19 @@ If satisfied, you may then create this table in the database by running the
290 311
     Creating table world_worldborders
291 312
     Installing custom SQL for world.WorldBorder model
292 313
 
293  
-The ``syncdb`` command may also prompt you to create an admin user; go ahead and
294  
-do so (not required now, may be done at any point in the future using the
  314
+The ``syncdb`` command may also prompt you to create an admin user; go ahead
  315
+and do so (not required now, may be done at any point in the future using the
295 316
 ``createsuperuser`` management command).
296 317
 
297 318
 Importing Spatial Data
298 319
 ======================
299 320
 
300 321
 This section will show you how to take the data from the world borders
301  
-shapefile and import it into GeoDjango models using the :ref:`ref-layermapping`.
302  
-There are many different different ways to import data in to a
303  
-spatial database -- besides the tools included within GeoDjango, you
304  
-may also use the following to populate your spatial database:
  322
+shapefile and import it into GeoDjango models using the
  323
+:ref:`ref-layermapping`.
  324
+There are many different ways to import data in to a spatial database --
  325
+besides the tools included within GeoDjango, you may also use the following to
  326
+populate your spatial database:
305 327
 
306 328
 * `ogr2ogr`_: Command-line utility, included with GDAL, that
307 329
   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
322 344
 library -- in other words, you'll be able explore all the vector data sources
323 345
 that OGR supports via a Pythonic API.
324 346
 
325  
-First, invoke the Django shell::
  347
+First, invoke the Django shell:
  348
+
  349
+.. code-block:: bash
326 350
 
327 351
     $ python manage.py shell
328 352
 
@@ -385,7 +409,8 @@ system associated with it -- if it does, the ``srs`` attribute will return a
385 409
     '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
386 410
 
387 411
 Here we've noticed that the shapefile is in the popular WGS84 spatial reference
388  
-system -- in other words, the data uses units of degrees longitude and latitude.
  412
+system -- in other words, the data uses units of degrees longitude and
  413
+latitude.
389 414
 
390 415
 In addition, shapefiles also support attribute fields that may contain
391 416
 additional data.  Here are the fields on the World Borders layer:
@@ -484,7 +509,9 @@ A few notes about what's going on:
484 509
   the shapefile. This ensures that string values are read and saved correctly
485 510
   from their original encoding system.
486 511
 
487  
-Afterwards, invoke the Django shell from the ``geodjango`` project directory::
  512
+Afterwards, invoke the Django shell from the ``geodjango`` project directory:
  513
+
  514
+.. code-block:: bash
488 515
 
489 516
    $ python manage.py shell
490 517
 
@@ -502,10 +529,12 @@ Try ``ogrinspect``
502 529
 Now that you've seen how to define geographic models and import data with the
503 530
 :ref:`ref-layermapping`, it's possible to further automate this process with
504 531
 use of the :djadmin:`ogrinspect` management command.  The :djadmin:`ogrinspect`
505  
-command  introspects a GDAL-supported vector data source (e.g., a shapefile) and
506  
-generates a model definition and ``LayerMapping`` dictionary automatically.
  532
+command  introspects a GDAL-supported vector data source (e.g., a shapefile)
  533
+and generates a model definition and ``LayerMapping`` dictionary automatically.
  534
+
  535
+The general usage of the command goes as follows:
507 536
 
508  
-The general usage of the command goes as follows::
  537
+.. code-block:: bash
509 538
 
510 539
     $ python manage.py ogrinspect [options] <data_source> <model_name> [options]
511 540
 
@@ -514,7 +543,9 @@ Where ``data_source`` is the path to the GDAL-supported data source and
514 543
 be used to further define how the model is generated.
515 544
 
516 545
 For example, the following command nearly reproduces the ``WorldBorder`` model
517  
-and mapping dictionary created above, automatically::
  546
+and mapping dictionary created above, automatically:
  547
+
  548
+.. code-block:: bash
518 549
 
519 550
     $ python manage.py ogrinspect world/data/TM_WORLD_BORDERS-0.3.shp WorldBorder --srid=4326 --mapping --multi
520 551
 
@@ -522,7 +553,8 @@ A few notes about the command-line options given above:
522 553
 
523 554
 * The ``--srid=4326`` option sets the SRID for the geographic field.
524 555
 * The ``--mapping`` option tells ``ogrinspect`` to also generate a
525  
-  mapping dictionary for use with :class:`~django.contrib.gis.utils.LayerMapping`.
  556
+  mapping dictionary for use with
  557
+  :class:`~django.contrib.gis.utils.LayerMapping`.
526 558
 * The ``--multi`` option is specified so that the geographic field is a
527 559
   :class:`~django.contrib.gis.db.models.MultiPolygonField` instead of just a
528 560
   :class:`~django.contrib.gis.db.models.PolygonField`.
@@ -571,7 +603,9 @@ Spatial Lookups
571 603
 ---------------
572 604
 GeoDjango extends the Django ORM and allows the use of spatial lookups.
573 605
 Let's do an example where we find the ``WorldBorder`` model that contains
574  
-a point.  First, fire up the management shell::
  606
+a point.  First, fire up the management shell:
  607
+
  608
+.. code-block:: bash
575 609
 
576 610
     $ python manage.py shell
577 611
 
@@ -592,8 +626,8 @@ a ``contains`` lookup using the ``pnt_wkt`` as the parameter::
592 626
 
593 627
 Here we retrieved a ``GeoQuerySet`` that has only one model: the one
594 628
 for the United States (which is what we would expect).  Similarly,
595  
-a :ref:`GEOS geometry object <ref-geos>` may also be used -- here the ``intersects``
596  
-spatial lookup is combined with the ``get`` method to retrieve
  629
+a :ref:`GEOS geometry object <ref-geos>` may also be used -- here the
  630
+``intersects`` spatial lookup is combined with the ``get`` method to retrieve
597 631
 only the ``WorldBorder`` instance for San Marino instead of a queryset::
598 632
 
599 633
     >>> from django.contrib.gis.geos import Point
@@ -641,9 +675,9 @@ __ http://spatialreference.org/ref/epsg/32140/
641 675
 Lazy Geometries
642 676
 ---------------
643 677
 Geometries come to GeoDjango in a standardized textual representation.  Upon
644  
-access of the geometry field, GeoDjango creates a `GEOS geometry object <ref-geos>`,
645  
-exposing powerful functionality, such as serialization properties for
646  
-popular geospatial formats::
  678
+access of the geometry field, GeoDjango creates a `GEOS geometry object
  679
+<ref-geos>`, exposing powerful functionality, such as serialization properties
  680
+for popular geospatial formats::
647 681
 
648 682
     >>> sm = WorldBorder.objects.get(name='San Marino')
649 683
     >>> sm.mpoly
@@ -706,7 +740,9 @@ as follows::
706 740
         (r'^admin/', include(admin.site.urls)),
707 741
     )
708 742
 
709  
-Start up the Django development server::
  743
+Start up the Django development server:
  744
+
  745
+.. code-block:: bash
710 746
 
711 747
     $ python manage.py runserver
712 748
 

0 notes on commit 804e32f

Please sign in to comment.
Something went wrong with that request. Please try again.