Merge branch 'master' into demo-manage-commands

.gitignore

@@ -74,3 +74,4 @@ src/vendor/
 
 # Includes
 !src/disclosures/js/lib
+site/

CHANGELOG.md

@@ -4,6 +4,7 @@ We follow the [Semantic Versioning 2.0.0](http://semver.org/) format.
 ## Unreleased
 - Added model function for exporting program as CSV
 - Added management command for purging test programs
+- Added docs/ directory and MkDocs framework to publish URL and CSV specs
 - Marked all non-settlement schools with the `settlement_school` tag of "demo"
 
 ## 2.2.0

README.md

@@ -30,6 +30,9 @@ Tools to help students make informed financial decisions about college.
 - [mock](https://github.com/testing-cabal/mock)
 - [coverage](https://coverage.readthedocs.org/en/latest/)
 
+### Data specifications
+- Requirements for submitting data for use in this tool can be found in [our specifications documentation](https://cfpb.github.io/college-costs/).
+
 ### Installation
 This project is not fully functional, but feel free to give it a spin. Here's how:
 - Install the setup dependencies if you don't have them.

docs/csv-spec.md

@@ -0,0 +1,46 @@
+## CSV specifications for program data
+The CSV should be UTF-8 encoded.  
+
+#### Column names and types for incoming college program data
+
+name | type | note
+:--- | :--- | :---
+ipeds_unit_id | integer | will be used as the canonical 6-digit school ID
+ope_id | string | alternate Dept. of Ed school ID as backup
+program_code | string | assumed unique within a school; <br>can't contain these characters: ; < > { } _
+program_name | string |
+program_length | integer | number of months in program
+program_level | integer | 0 = Non-degree-granting<br> 1 = Certificate<br> 2 = Associate<br> 3 = Bachelor's<br> 4 = Graduate
+accreditor | string | often will be blank
+median_salary | integer |
+average_time_to_complete | integer | in months
+books_supplies | integer | annual cost of books and supplies
+campus_name | string
+cip_code | string | used to look up related career/field
+completion_rate | float | 0.41 (would signify 41%)
+completion_cohort | integer | number of students who enrolled in the program
+completers | integer | number in cohort who completed the program
+default_rate | float |0.25
+job_placement_rate | float | 0.33
+job_placement_note | string | optional note on job rate
+mean_student_loan_completers | integer | average of amounts grads owe
+median_student_loan_completers | integer | median of amounts grads owe
+soc_codes | string | pipe-separated list of related career/fields
+total_cost | integer | total attendance cost
+tuition_fees | integer | annual cost of tuition and fees
+
+#### Change log
+Change | date
+:----- | :---
+Noted ipeds_unit_id is an integer | 2016-08-24
+Added underscore to list of characters not allowed in a program code | 2016-08-24
+Added notes indicating that books_supplies and tutiion_fees should be annual values | 2016-07-26
+Added 'completion_cohort' and 'completers' values | 2016-07-11
+Added illegal character list for program codes | 2016-07-01
+Added requirement for UTF-8 encoding | 2016-06-29
+Restored 'program_length' field, which was initially provided as 'monthsinprogram' | 2016-02-14
+Added 0 as possible value for program_level, to match Ed. Dept. mappings | 2016-02-11
+Changed average_salary to median_salary | 2016-01-28
+Job_placement_note type changed to string | 2016-01-12
+Note added to program_level to specify values | 2016-01-12
+Fixed typo in note on median_student_loan_completers: it represents median not mean | 2016-01-12

docs/index.md

@@ -0,0 +1,7 @@
+# Data specifications
+
+This is specification documentation for the [college-costs](https://github.com/cfpb/college-costs) project.
+
+The project takes in and displays information about the costs and benefits of enrolling in a collegiate program.
+
+This documentation spells out how information to be used should be formatted and delivered.

docs/notification-spec.md

@@ -0,0 +1,30 @@
+## Notifications
+
+School that need to receive notifications of completed disclosures have two ways to be notified.  
+The first, and preferred, method is via an API endpoint that the school will maintain.  
+The endpoint must be able to receive POST requests with a payload in this form:
+
+```
+oid: f38283b5b7c939a058889f997949efa566c616c5  
+time: 2016-01-13T16:04:37.777104+00:00  
+errors: none
+```
+
+## Feilds
+**oid** is a 40-character hex string from the offer url to allow the school to match an offer to a student.  
+**time** is a UTC timestamp string representing when the disclosure notification was generated.  
+**errors** is a string indicating whether the disclosure was valid. It will have one of two values:  
+
+- "none"  
+This will confirm that the disclosure was completed and is valid.
+
+- "INVALID: student indicated the offer information is wrong"  
+This indicates that the student clicked on the link labeled "No, this is not my information"  
+This option is intended to catch cases where the student was given the wrong URL or a faulty URL.  
+In this case, a new oid will need to be generated in order to complete a valid disclosure; oid values are allowed to generate only one notification.
+
+## Email notification
+Endpoint notifications are preferred because they are more reliable and simpler to automate.  
+Schools that can't set up endpoints can get notifications via email.
+
+

docs/url-spec.md

@@ -0,0 +1,67 @@
+## URL specifications for offer data
+
+#### Mapping url fields to data points
+Values should be annual unless otherwise specified.
+
+This scheme results in URLs about 400 characters long, well below browser/server character limits.  
+Here's what a full URL would look like:
+<br>
+consumerfinance.gov/paying-for-college2/<br>
+understanding-your-financial-aid-offer/offer/?<br>
+iped=204316&pid=business-1042&oid=a9e280139f3238cbc9702c7b0d62e5c238a835a0<br>
+&book=650&gib=3000&gpl=1000&hous=3000&insi=4.55&insl=3000&inst=36<br>
+&mta=3000&othg=100&othr=500&parl=10000&pelg=1500&perl=3000<br>
+&ppl=1000&prvl=3000&prvf=2.1&prvi=4.55&schg=2000&stag=2000<br>
+&subl=3500&totl=40000&tran=500&tuit=38976&unsl=2000&wkst=3000
+<br>
+
+#### Value details
+- School IDs (iped) must be an integer.
+- Program IDs (pid) must not contain these characters: `; < > { } _`
+- Offer IDs (oid) must contain only hex characters: a-f, 0-9
+
+The values below are just examples to show type.   
+Rates can be more precise than two decimal places, but may be rounded for display.  
+Dollar amounts should be in rounded whole numbers.  
+
+In URL | Description | Example value | Note
+:----- | :---------  | :------------ | :---
+iped | college ID | 123456 | 6-digit integer: the unit ID from IPEDS
+pid  | program ID | business-981 | string: this would be combined with school ID to get a unique program
+oid  | offer ID | 9e0280139f3238cbc970<br>2c7b0d62e5c238a835d0 | 40-hex-character hashed value: represents one offer to one student. First 7 characters should be given to the student for matching with the disclosure page.
+book | books | 650 | books + supplies
+gib  | gi bill | 3000 |
+gpl  | grad plus loans | 1000 |
+hous | housing | 3000 | room + board
+insi | institutional (school) loan interest rate | 0.0455 | rates should be expressed as coefficients, so 4.55% is 0.0455
+insl | institutional loans (all) | 3000 | including tuition payment plans
+inst | institutional loan term | 48 | in months
+mta  | military assistance | 3000 |
+othg | other grants and scholarships | 100 |
+othr | other costs | 500 |
+parl | parent loans | 10000 | includes all family contributions (except parent plus loans)
+pelg | pell_grant | 1500 |
+perl | perkins loans | 3000 |
+ppl  | parent plus loans | 1000 |
+prvl | private loans | 3000 |
+prvf | private loan origination fee | 0.021 | coefficient, not percentage point
+prvi | private loan interest | 0.0455 | coefficient, not percentage point
+schg | school grants and scholarships | 2000 |
+stag | state grants | 2000 |
+subl | subsidized loans | 3500 |
+totl | total direct cost | 40000 | tuition, fees, books, supplies
+tran | transportation | 200 |
+tuit | tuition | 38976 | annual tuition + fees
+unsl | unsubsidized loans | 2000 |
+wkst | work study | 3000 |
+
+#### Change log
+Change | date
+:----- | :---
+Added underscore to list of characters not allowed in a program ID | 2016-08-24
+Added note that values should be annual unless otherwise specified | 2016-07-26
+Added note for parl: it represents all family contributions | 2016-07-19
+Added notes on expressing rates and fees | 2016-07-15
+Added `totl` field | 2016-06-22
+Added `prvf` and `inst` fields | 2016-05-27
+Removed the `fam` and `ta` fields | 2015-01-12

mkdocs.yml

@@ -0,0 +1,17 @@
+site_name: college-costs
+pages:
+- Introduction: index.md
+- Specifications:
+    - CSV spec for program data: csv-spec.md
+    - URL spec for offer data: url-spec.md
+    - Notification spec validating offers: notification-spec.md
+
+theme: mkDOCter
+extra:
+    brand_color: "#2CB34A"
+    logo_url: https://cfpb.github.io/img/logo_210.png
+    logo_alt: Consumer Financial Protection Bureau
+
+markdown_extensions:
+    - admonition
+    - tables

requirements/docs.txt

@@ -0,0 +1,14 @@
+Markdown==2.3.1
+PyYAML==3.10
+backports-abc==0.4
+certifi==2016.8.2
+click==3.3
+django-livereload==1.2
+livereload==2.3.2
+mkdocs==0.15.3
+mkdocs-bootstrap==0.1.1
+mkdocs-bootswatch==0.1.0
+singledispatch==3.4.0.3
+six==1.9.0
+tornado==4.1
+mkDOCter