updated documentation

README.rst

@@ -27,11 +27,6 @@ Project Goals
      2. create voting relationship between legislators and legislation 
 4. Build tools on top of data 
 
-To encourage as many contributions as possible we aren't saying "write in Python" 
-or anything, but we do need the code to follow a few guidelines.
-
-For details on how scripts should be written and how they should run see :doc:`scripts/pyutils/README` (or :doc:`scripts/rbutils/README`).
-For details on how data should be stored see :doc:`data/README`.
 
 .. _usage:
 
@@ -83,24 +78,28 @@ See LICENSING for the full terms of the GPLv3.
 Requirements
 ============
 
-It is preferred for the sake of maintenance that scripts are written in 
-Python, several Ruby scripts also exist if you are unfamiliar with Python.
+Although we have previously allowed you to write parsers in your
+language of choice, for the sake of maintenance we *highly* encourage
+you to write your parsers in Python. Currently Python is the only
+language we are supporting with our documentation and tools.  If you
+would like to contribute in a language other than Python, please send
+an email to `Fifty State Project Google Group
+<http://groups.google.com/group/fifty-state-project>`_ so we can
+discuss the issue.
+
+For details on how scripts should be written and how they should run see :doc:`scripts/pyutils/README`.
+
+If you are completely unfamiliar with Python there is other things you
+can do to help with the government transparency movement.  Ruby developers are encouraged to work on the `Congrelate <http://congrelate.com>`_ Project.  For other project ideas please join the `Sunlight Labs Google Group <http://groups.google.com/group/sunlightlabs>`_.
 
-If you are completely unfamiliar with Python or Ruby writing a scraper in
-another language is preferred over not contributing at all but given the
-number of scripts already written in Python you are strongly encouraged  to
-consider it first.
 
-:ref:`Python Libraries <python-dependencies>`
-Python (2.5+)
+.. _dependencies:
+
+Dependencies
 -------------
+* Python (2.5+)
 * BeautifulSoup
 * html5lib
 * simplejson if on Python 2.5
 * (this list is out of date, refer to specific scripts/state directories for dependencies)
 
-Ruby (1.8.*+)
--------------
-* hpricot (gem install hpricot)
-* fastercsv (gem install fastercsv)
-* mechanize (gem install mechanize)

docs/conf.py

@@ -46,9 +46,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

index.rst

@@ -9,15 +9,15 @@ Fifty State Project Documentation
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    README
    scripts/pyutils/README
    scripts/rbutils/README
    scripts/state-specific-index
-   script/contributing
-   data/README
-   data/data-format
+   scripts/contributing
+
+
 
 Indices and tables
 ==================

scripts/contributing.rst

@@ -13,60 +13,69 @@ you can ask questions and make suggestions regarding the project).
 What All Developers Should Know
 ==============================
 
-Choosing a Language
--------------------
-It is preferred for the sake of maintenance that scripts are written in 
-Python, several Ruby scripts also exist if you are unfamiliar with Python.
-
-If you are completely unfamiliar with Python or Ruby writing a scraper in
-another language is preferred over not contributing at all but given the
-number of scripts already written in Python you are strongly encouraged to
-consider it first.
-
 Dependencies
 -------------
 
 Regardless of whichever language you choose we prefer that you keep
-the number of dependencies to a minumum.  For a list of libaries that
-we encourage you to use see :ref:`python-dependencies`.
-
-
+the number of dependencies to a minimum.  For a list of libraries that
+we encourage you to use see :ref:`dependencies`.
 
 Licensing
 ---------
 For licensing information, see :ref:`licensing`.
 
-
 Obtaining Source Code
 ---------------------
 
 Code can be pulled via git from the following location:
 ::
     git://github.com/sunlightlabs/fiftystates.git
 
-You are encoraged to create a `github <http://github.com>`_ account
+You are encouraged to create a `github <http://github.com>`_ account
 and create a fork from sunlightlab's `fiftystate project
 <http://github.com/sunlightlabs/fiftystates/tree/master>`_ code to work off of.
 
+
+Writing a Parser
+================
+
 Creating a New State Parser
 ---------------------------
 
 If a parser for the state you are working on does not already exist,
 you should create a directory under *scripts* and name it after the
-offical two letter abbreviation of the state name.  The name of the
+official two letter abbreviation of the state name.  The name of the
 directory should be written in lowercase.  Each state directory file
 should have at least two files.  One file should be called STATUS.
-See :ref:`STATUS`. for information on what should be in this file.
+See `Communicating Code Status`_.. for information on what should be in this file.
 The second file should be an executable that collects and writes the
-state legilative data into the *data*/*your state* directory in json
-format.   See :ref:`database` for more information on how to structure
-you data.  If you are using our Python or Ruby tools you do not need
-to worry on how to structure that data you collect because our tools
-write the database files for you.
+state legislative data into the *data*/*your state* directory in json
 
-Submitting Code
----------------
 
+Python Parser Tools
+-------------------
+
+To aid in development, we have created tools that take care of writing
+the data to the database.  The source code of these tools is located
+in the *scripts/pyutils* directory, please take a look at the
+:ref:`pythonapi` for more information.
+
+For your convenience we have created some stub files that you can
+use as a starting point for your parser.  They can be found under
+*scripts/python_template*
+
+Running Your Parser
+-------------------
+
+When you test your parser please run it from the top level of the
+*fiftystates* directory (ie: python ./scripts/ct/get_legislation.py -y
+2008 -upper).  This is where we will be running the scripts from and
+it will ensure all data gets written to the proper place.  If you use
+our skeleton code, it imports the libraries assuming you will be running the
+script from the *fiftystates* directory.
+
+Submitting Code
+===============
 
 .. _STATUS:
 Communicating Code Status
@@ -82,16 +91,17 @@ the status of the parser. The following text can be used as a template
     sponsors: no
     actions: no
     votes: no
-    contributors: your name <your@email.com>
+    contributors: your name, somebody else's name
+    contact: wendy@email.com
     executable: get_legislation.py
     notes:
-
+- This file should be written in the style `described here <http://docs.python.org/library/configparser.html>`_
 - You should write the full name of the state you are parsing
   in-between the square brackets.
 - under **start_year**, you should write the first year you can get
   legislative data from
-- **contributers** should be a comma seperated list of the names and
-   emails of people who contributed to the state's scraper.
+- **contributors** should be a comma separated list of the names of the people who contributed to the state's scraper.
+- **contact* is the email address of the lead developer
 - **notes** is any notes you have on the code, including any bugs or
   issues.  You should also include information on any extra data you
   may be scraping.
@@ -109,27 +119,15 @@ message to the `Fifty State Project Google Group
 <http://groups.google.com/group/fifty-state-project>`_ so we can find
 someone else to take over your states.
 
-Writing a Parser in Python
-==========================
-If you choose to write your parser in Python, we have created some
-tools that take care of writing data to the database.  The source code
-of these tools is located in the *scripts/pyutils* directory
-
-For your convience we have created some stub files that you can edit
-and flesh out for your parser.  They can be found under
-*scripts/python_template*
-
-
-Writing a Parser in Ruby
-==========================
-If you choose to write your parser in Python, we have created some
-tools that take care of writing data to the database.  The source code
-of these tools is located in the *scripts/rbutils* directory
-
-Writing a Parser in Some Other Language
-======================================= 
-
-If you chose to write your parser in a language other than Python and
-Ruby, please conform to our usage and output standards. See
-:ref:`usage` to see what the interface of your executable should
-be. See :ref:`database` for information on how to structure your data.
+State Specific Documentation
+----------------------------
+If the *notes* section of your STATUS is not enough to express the problems or usage of your scraper, we encourage you to write state specific documentation in ReStructuredText format and hook it into our documentation.  For an example of a state that does that, take a look at *ca*.
+
+Our documentation is generated using `sphinx
+<http://sphinx.pocoo.org/>`_.  To link in documentation from your
+state, write your documentation up in a `ReStructuredText
+<http://docutils.sourceforge.net/rst.html>`_ format in *README.rst* in
+your state script directory.  Then add the relative path to your
+documentation (without the .rst extension) to
+*scripts/state-specific-index.rst*. You can then use the *Makefile*
+under the *docs* directory to build and check your documentation.