Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Updating docs

  • Loading branch information...
commit 6ba8aefb0e259780771ba1c9e10ce9ebdd1b6aa1 1 parent 23a93f1
pw@slinktopp authored
Showing with 131 additions and 72 deletions.
  1. +71 −45 NOTES.txt
  2. +60 −27 README.txt
View
116 NOTES.txt
@@ -1,25 +1,27 @@
-Random grab-bag of todos and historical project info
+=================
+Development Notes
+=================
-OFFICES TA CARES ABOUT
-======================
- * City Council (by council districts)
- * Controller (citywide)
- * Mayor (citywide)
+Code Notes
+==========
- * Public Advocate (citywide)
- * Borough President (by borough)
-
- * DA (manhattan only for now; by borough)
+Please Add Migrations!
+----------------------
+When adding new data, or modifying existing data, you should provide
+migrations so your changes can be reproduced.
+You'll want to look up the docs for SQLAlchemy-migrate and learn how
+to use the manage.py script and write migrations. You can steal ideas
+for migrations by looking at existing scripts. Maybe bad ideas, but
+they've more or less worked so far ;-)
-
-DATA
-======
+Data Sources
+------------
http://www.nyc.gov/html/dcp/html/bytes/dwndistricts.shtml
@@ -29,29 +31,42 @@ DATA
http://www.nyc.gov/html/dcp/download/bytes/nycc_08cav.zip
-CODE NOTES
-=============
-
+Random SQL query examples
+--------------------------
-* This apparently works to find my home districts (LONGITUDE FIRST):
+This apparently works to find my home districts (LONGITUDE FIRST)::
select * from districts where districts.geometry is not NULL and st_contains(districts.geometry, ST_GeomFromText('POINT(-73.96805047988892 40.677578720206355 )', 4326));
+Votesmart usage examples
+-------------------------
-NEW DATA MODEL
-======================
+::
- From a location, we look up one or more districts (they can overlap).
- But we realy need to factor out some data from the districts.
+ nyc_id = 898
+ nyc_officials = votesmart.local.getOfficials(nyc_id)
+ pprint([(c.lastName, c.title, c.officeParties) for c in nyc_officials])
- * An Election has these direct attributes:
+
+
+New Data Model as of August 2009
+---------------------------------
+
+From a location, we look up one or more districts (they can overlap).
+But we realy need to factor out some data from the districts.
+
+
+* An Election has these direct attributes:
+
- election date
+
- name
+
- stagename ("Primary" | "General")
- * Person has these attributes:
+* Person has these attributes:
- fullname
@@ -62,7 +77,7 @@ NEW DATA MODEL
- arbitrary other key/vals via people_meta_table
- An Election takes place in N Districts, each modeled via a
+* An Election takes place in N Districts, each modeled via a
Race association class. (many-to-many)
- An Race has references to one District and one
@@ -82,7 +97,7 @@ NEW DATA MODEL
- a Person has backrefs to at most 1 Race, and thus
indirectly to 0-1 Elections and 0-1 Districts.
- Given all that, convenience methods could yield useful things like
+* Given all that, convenience methods could yield useful things like
"latest election a candidate ran in".
So, eg. to find incumbents and candidates given an address and a
@@ -92,43 +107,54 @@ NEW DATA MODEL
matches the date, and Race.District.geography matches
the address.
- - for each Race:
- eg. Race(election=Election('NY Primaries 2009'),
- district=District('Brooklyn'),
- office='Borough President')
+ - for each Race: eg::
+
+ Race(election=Election('NY Primaries 2009'),
+ district=District('Brooklyn'),
+ office='Borough President')
- - from Race.district, yield the incumbents
- eg. Person('Bob Jones', incumbent_office='Borough President',
- incumbent_district=District('Brooklyn'))
+ - from Race.district, yield the incumbents, eg::
+
+ Person('Bob Jones', incumbent_office='Borough President',
+ incumbent_district=District('Brooklyn'))
- yield all Race.candidates
eg. Person('Lisa James', incumbent_office=None)
-DEFERRED: Slightly more complex again
--------------------------------------
+DEFERRED: Slightly more complex data model
+------------------------------------------
Basically same as above, except Office becomes a first-class object,
and we add a concept of Party.
-Votesmart usage examples:
------------------------------
+Admin UI
+--------
-nyc_id = 898
-nyc_officials = votesmart.local.getOfficials(nyc_id)
-pprint([(c.lastName, c.title, c.officeParties) for c in nyc_officials])
+Might want one of these.
+Maybe bootstrap it with FormAlchemy? and/or its pylons admin UI?
+http://docs.formalchemy.org/current/ext/pylons.html#administration-interface
+Random Historical Notes
+========================
-ADMIN UI
-========
+Offices TA Cares About
+----------------------
-Might want one of these.
-Maybe bootstrap it with FormAlchemy? and/or its pylons admin UI?
-http://docs.formalchemy.org/current/ext/pylons.html#administration-interface
+ * City Council (by council districts)
+
+ * Controller (citywide)
+
+ * Mayor (citywide)
+
+ * Public Advocate (citywide)
+
+ * Borough President (by borough)
+
+ * DA (manhattan only for now; by borough)
-TO DO
View
87 README.txt
@@ -1,27 +1,60 @@
-This file is for you to describe the purplevoter application. Typically
-you would include information such as the information below:
+====================
+About Purplevoter
+====================
+
+This is the software behind http://whoismygov.org.
+
+It provides a web UI and a web service that can be used to look up
+federal, state, and (when we have the data) local elected officials
+and candidates.
+
+Originally created by Anil Makhijani, it is being developed currently
+by the TOPP Labs division of The Open Planning Project
+(http://topplabs.org/, http://openplans.org).
+For more info, contact Paul Winkler (pw @ openplans.org).
+
+Some development work was done in partnership with Transportation
+Alternatives (http://www.transalt.org/).
+
Installation and Setup
======================
-You need PostGIS installed first.
+Prerequisites
+-------------
+
+You need PostGIS (http://postgis.refractions.net/) installed first.
+
+We recommend installing Purplevoter in a virtualenv
+(http://pypi.python.org/pypi/virtualenv).
+
+Get the Source
+---------------
-Install ``purplevoter`` using easy_install::
+You can use Mercurial (hg) to get the source code, like so::
- easy_install purplevoter
+$ hg clone https://bitbucket.org/slinkp/purplevoter/
+
+Install
+-------
+
+Install the software; if using virtualenv, be sure to activate the
+virtualenv first. Then::
+
+$ python setup.py develop
Then you are almost ready to go, except you need some data.
Database Bootstrapping
-======================
-
+----------------------
+
First tweak the development.ini config file as appropriate and then
setup the application.
To set up the database:
-First create a postgres user named pvoter. Then:
+First create a postgres user named pvoter. Then::
$ createdb -T template_postgis -O pvoter -E utf8 pvoter
@@ -31,42 +64,43 @@ http://code.djangoproject.com/wiki/GeoDjangoUbuntuInstall
Then try the createdb command again.
-Next, fix up some table ownership:
+Next, fix up some table ownership::
$ psql -c "alter table geometry_columns owner to pvoter;" pvoter
$ psql -c "alter table spatial_ref_sys owner to pvoter;" pvoter
-Then to populate the data:
+Then to populate the data, first be sure you have activated your
+virtualenv if using one, then::
-$ source bin/activate
$ paster setup-app --name=pvoter development.ini
$ python manage.py version_control
$ python manage.py upgrade
+Start the Dev Server
+--------------------
+
+Start it like any other Pylons app::
-Data Migrations
-===============
+$ paster serve development.ini
-When adding new data, or modifying existing data, you should provide
-migrations so your changes can be reproduced.
-You'll want to look up the docs for SQLAlchemy-migrate and learn how
-to use the manage.py script and write migrations. You can steal ideas
-for migrations by looking at existing scripts. Maybe bad ideas, but
-they've worked so far ;-)
+Development Notes
+=================
+See DEVELOPMENT_NOTES.txt.
-Production Deployment
-=====================
-We might eventually use mod_wsgi. For now, we run Paste under the
-control of supervisord, and assume you can set up Apache or similar to
-reverse-proxy it.
+Deployment Notes
+================
+
+We might eventually use mod_wsgi. For now, we (TOPP) run Paste under
+the control of supervisord (http://supervisord.org/), and assume you
+can set up Apache or another web server to reverse-proxy it.
The source includes a supervisord.conf suitable for running the paste
server under the control of supervisord, which will restart it if it
-ever crashes. To use supervisord::
+ever crashes. To use supervisord:
* I assume you've built in a virtualenv as described above.
@@ -79,7 +113,7 @@ ever crashes. To use supervisord::
* In the parent of the virtualenv, create an etc/ subdirectory
and symlink both production.ini and supervisord.conf into it.
- Also create a logs/ subdirectory.
+* Also create a logs/ subdirectory.
Then you can run $VIRTUALENV/bin/supervisord to start things up.
@@ -91,4 +125,3 @@ To restart the paste server, run:
$VIRTUALENV/bin/supervisorctl restart pvoter
-
Please sign in to comment.
Something went wrong with that request. Please try again.