Documentation cleanup

coderholic · Apr 5, 2012 · 653571b · 653571b
1 parent 9f1b7ba
commit 653571b
Show file tree

Hide file tree

Showing 2 changed files with 71 additions and 101 deletions.
diff --git a/README.md b/README.md
@@ -1,112 +1,38 @@
- django-cities -- *Place models and data for Django apps*
-=========================================================
+# django-cities
+### Place models and worldwide place data for Django
 
-This add-on provides models and commands to import country/region/city data into your database.
-The data is pulled from [GeoNames](http://www.geonames.org/) and contains:
+----
 
-  - localized names
-  - geographical codes
-  - postal codes
-  - geo-coords
-  - population
+django-cities provides you with place related models (eg. Country, Region, City) and data (from [GeoNames](http://www.geonames.org/)) that can be used in your django projects.
 
-Your database must support spatial queries, see [GeoDjango]
-(https://docs.djangoproject.com/en/dev/ref/contrib/gis/) for setup.
+Authored by [Ben Dowling](http://www.coderholic.com), and some great [contributors](https://github.com/coderholic/django-cities/contributors).
 
-For more information see [this blog post]
-(http://www.coderholic.com/django-cities-countries-regions-cities-and-districts-for-django/).
+----
 
+### Requirements
 
- Examples
---------------------------
-Finding all London boroughs:
+Your database must support spatial queries, see the [GeoDjango documentation](https://docs.djangoproject.com/en/dev/ref/contrib/gis/) for details and setup instructions.
 
-```python
-    london = City.objects.filter(country__name='United Kingdom').get(name='London')
-    boroughs = District.objects.filter(city=london)
-```
 
-Nearest city to a given geo-coord (longitude, latitude):
+### Setup
 
-```python
-    City.objects.distance(Point(1, 51)).order_by('distance')[0]
-    <City: Dymchurch, Kent, United Kingdom>
-```
+Either clone this repository into your project, or install with ```pip install django-cities```
 
-5 Nearest cities to London:
+You'll need to add ```cities``` to ```INSTALLED_APPS``` in your projects settings.py file:
 
-```python
-    london = City.objects.filter(country__name='United Kingdom').get(name='London')
-    nearest = City.objects.distance(london.location).exclude(id=london.id).order_by('distance')[:5]
-```
-
-Get a list of all cities in a state or county:
-
-```python
-    City.objects.filter(country__name="United States", region__name="Texas")
-    City.objects.filter(country__name="United States", subregion__name="Orange County")
-```
-
-Get all countries in Japanese preferring official names if available, fallback on ASCII names:
-
-```python
-    [country.alt_names_ja.get_preferred(default=country.name) for country in Country.objects.all()]
-```
-
-Use alternate names model to get Vancouver in Japanese:
-
-```python
-    geo_alt_names[City]['ja'].objects.get_preferred(geo__name='Vancouver', default='Vancouver')
-```
-
-Gather names of Tokyo from all CITIES_LOCALES:
-
-```python
-    [name for locale in cities.conf.settings.locales
-        for name in geo_alt_names[City][locale].objects.filter(geo__name='Tokyo')]
-```
-
-Get all postal codes for Ontario, Canada (only first 3 letters available due to copyright restrictions):
-
-```python
-    postal_codes['CA'].objects.filter(region__name='Ontario')
-```
-
-Get region objects for US postal code:
-
-```python
-    Region.objects.filter(postal_codes_US__code='90210')
-    [<Region: California, United States>]
-    Subregion.objects.filter(postal_codes_US__code='90210')
-    [<Subregion: Los Angeles County, California, United States>]
-```
-
- Install
---------------------------
-- Run: `python setup.py install`
-- Add/Merge the following into your *settings.py*:
-
------------------------------------------------------------
 ```python
 INSTALLED_APPS = (
+    ...
     'cities',
 )
 
-LOGGING = {
-    'handlers': {
-        'console':{
-            'level':'DEBUG',
-            'class':'logging.StreamHandler',
-        },
-    },
-    'loggers': {
-        'cities': {
-            'handlers': ['console'],
-            'level': 'INFO',
-        }
-    }
-}
+Then run ```./manage.py syncdb``` to create the required database tables, and ```./manage.py cities --import=all``` to import all of the place data. **NOTE:** This can take a long time.
+
+### Configuration
+
+There are various optional configuration options you can set in your ```settings.py```:
 
+```python
 CITIES_FILES = {
     # Uncomment below to import all cities with population > 1000 (default is > 5000)
     #'city': {
@@ -130,15 +56,59 @@ CITIES_PLUGINS = [
     'cities.plugin.postal_code_ca.Plugin',  # Canada postal codes need region codes remapped to match geonames
 ]
 ```
------------------------------------------------------------
 
-- Sync your database with the new models: `manage.py syncdb`
-- Populate or update your database: `manage.py cities`
+### Examples
+
+This repostitory contains an example project which lets you browse the place hierarchy. See the ```example``` directory. Below are some small snippets to show you the kind of things that are possible:
+
+Finding all London boroughs:
+
+```python
+# Find the 5 most populated countries in the World
+>>> Country.objects.order_by('-population')[:5]
+[<Country: China>, <Country: India>, <Country: United States>, <Country: Indonesia>, <Country: Brazil>]
+
+# Find what country the .ly TLD belongs to
+>>> Country.objects.get(tld='ly')
+<Country: Libya>
+
+
+# 5 Nearest cities to London
+
+    london = City.objects.filter(country__name='United Kingdom').get(name='London')
+    nearest = City.objects.distance(london.location).exclude(id=london.id).order_by('distance')[:5]
+
+# All cities in a state or county
+
+    City.objects.filter(country__name="United States", region__name="Texas")
+    City.objects.filter(country__name="United States", subregion__name="Orange County")
+
+
+# Get all countries in Japanese preferring official names if available, fallback on ASCII names:
+
+[country.alt_names_ja.get_preferred(default=country.name) for country in Country.objects.all()]
+
+
+# Use alternate names model to get Vancouver in Japanese
+
+    geo_alt_names[City]['ja'].objects.get_preferred(geo__name='Vancouver', default='Vancouver')
+
+
+# Get region objects for US postal code:
 
+    Region.objects.filter(postal_codes_US__code='90210')
+    [<Region: California, United States>]
+    Subregion.objects.filter(postal_codes_US__code='90210')
+    [<Subregion: Los Angeles County, California, United States>]
+
+```
+
+### Notes
 
- Notes
---------------------------
 The localized names and postal code models/db-tables are created dynamically based on your settings.
+
 Some datasets are very large (> 100 MB) and take time to download / import, and there's no progress display.
+
 Data will only be downloaded / imported if it is newer than your data, and only matching rows will be overwritten.
+
 The cities manage command has options, see --help.  Verbosity is controlled through LOGGING.
diff --git a/setup.py b/setup.py
@@ -11,10 +11,10 @@ def read(fname):
 setup(
     name='django-cities',
     version='0.2',
-    description='Place models and data for Django apps',
-    author='Dan Carter (original by Ben Dowling)',
-    author_email='carterd@gmail.com',
-    url='https://github.com/Kometes/django-cities',
+    description='Place models and worldwide place data for Django'
+    author='Ben Dowling',
+    author_email='ben.m.dowling@gmail.com',
+    url='https://github.com/coderholic/django-cities',
     packages=find_packages(),
     include_package_data=True,
     zip_safe=False,