v2 documentation for ViewSets

- now with markdown
- crispy forms used for better modals
- coreapi added per docs

requirements/base.txt

@@ -10,3 +10,6 @@ django-taggit-serializer==0.1.5
 six==1.10.0
 djangorestframework-gis==0.11.2
 django-filter==1.0.4
+django-crispy-forms==1.6.1
+markdown==2.6.8
+coreapi==2.3.1

whats-open/api/views.py

@@ -2,6 +2,9 @@
 api/views.py
 
 Rest Framework Class Views
+
+Each ViewSet determines what data is returned when an API endpoint is hit. In
+addition, we define filtering and documentation for each of these endpoints. 
 """
 # Future Imports
 from __future__ import (absolute_import, division, print_function,
@@ -25,29 +28,61 @@ class AlertViewSet(viewsets.ReadOnlyModelViewSet):
     Some type of notification that is displayed to clients that conveys a message.
 
     Past examples include:
-        - random closings
-        - modified schedules being in effect
-        - election reminder
-        - advertising for other SRCT projects
+
+    - Random closings
+    - Modified schedules being in effect
+    - Election reminder
+    - Advertising for other SRCT projects
 
     Alerts last for a period of time until the information is no longer dank.
 
-    GET /api/alerts/
+    ---
+
+    ## Default behavior
+
+    [GET /api/alerts/](/api/alerts/?format=json)
+
     Return all Alert objects.
 
-    Built-in query parameters:
+    ## Built-in query parameters
+
+    ### **Search**
+
+    [GET /api/alerts/?search=](/api/alerts/?search=&format=json)
 
-    GET /api/alerts/?search=
     Query parameter that returns objects that match a keyword provided in the search.
 
-    GET /api/alerts/?ordering=
+    **Example Usage**
+
+    [GET /api/alerts/?search=srct](/api/alerts/?search=srct&format=json)
+
+    Return any Alert objects that have the string "srct" located in one of its fields.
+
+    ### **Ordering**
+
+    [GET /api/alerts/?ordering=](/api/alerts/?ordering=&format=json)
+
     Query parameter that orders the returned objects based on the provided field to order by.
 
-    Additionally, you can query against any field you like:
+    **Example Usage**
+
+    [GET /api/alerts/?ordering=urgency_tag](/api/alerts/?ordering=urgency_tag&format=json)
 
-    ie.
-    GET /api/alerts/?urgency_tag=major
-    will return the Alert objects that are tagged as "major" urgency.
+    Return all Alert objects ordered by urgency_tag ascending.
+
+    [GET /api/alerts/?ordering=-urgency_tag](/api/alerts/?ordering=-urgency_tag&format=json)
+
+    Return all Alert objects ordered by urgency_tag descending.
+
+    ### **Field filtering**
+
+    You can query directly against any field.
+
+    **Example Usage**
+
+    [GET /api/alerts/?urgency_tag=major](/api/alerts/?urgency_tag=major&format=json)
+
+    Return all Alert objects that are tagged as "major" urgency.
     """
     # All model fields that are available for filtering
     FILTER_FIELDS = (
@@ -79,27 +114,59 @@ class CategoryViewSet(viewsets.ReadOnlyModelViewSet):
     """
     A Category is a grouping of Facilities that serve a common/similar purpose.
 
-    ex.
-        - Dining
-        - Gyms
-        - Study areas (Libraries, The Ridge, JC, etc)
+    Examples:
+
+    - Dining
+    - Gyms
+    - Study areas (Libraries, The Ridge, JC, etc)
+
+    ---
+
+    ## Default behavior
+
+    [GET /api/categories/](/api/categories/)
 
-    GET /api/categories/
     Return all Category objects.
 
-    Built-in query parameters:
+    ## Built-in query parameters
+
+    ### **Search**
+
+    [GET /api/categories/?search=](/api/categories/?search=&format=json)
 
-    GET /api/categories/?search=
     Query parameter that returns objects that match a keyword provided in the search.
 
-    GET /api/categories/?ordering=
+    **Example Usage**
+
+    [GET /api/categories/?search=din](/api/categories/?search=din&format=json)
+
+    Return all Category objects that have a field that matches the string "din".
+
+    ### **Ordering**
+
+    [GET /api/categories/?ordering=](/api/categories/?ordering=&format=json)
+
     Query parameter that orders the returned objects based on the provided field to order by.
 
-    Additionally, you can query against any field you like:
+    **Example Usage**
+
+    [GET /api/categories/?ordering=name](/api/categories/?ordering=name&format=json)
+
+    Return all Category objects filtered by name ascending.
+
+    [GET /api/categories/?ordering=-name](/api/categories/?ordering=-name&format=json)
+
+    Return all Category objects filtered by name descending.
+
+    ### **Field filtering**
+
+    You can query directly against any field.
+
+    **Example Usage**
 
-    ie.
-    GET /api/categories/?name=dining
-    will return the Category object that is named "dining".
+    [GET /api/categories/?name=dining](/api/categories/?name=dining&format=json)
+
+    Return the Category object that is named "dining".
     """
     # All model fields that are available for filtering
     FILTER_FIELDS = (
@@ -128,22 +195,53 @@ class LocationViewSet(viewsets.ReadOnlyModelViewSet):
     """
     Represents a specific location that a Facility can be found.
 
-    GET /api/locations/
+    ---
+
+    ## Default behavior
+
+    [GET /api/locations/](/api/locations/?format=json)
+
     Return all Location objects.
 
-    Built-in query parameters:
+    ## Built-in query parameters
+
+    ### **Search**
+
+    [GET /api/locations/?search=](/api/locations/?search=&format=json)
 
-    GET /api/locations/?search=
     Query parameter that returns objects that match a keyword provided in the search.
 
-    GET /api/locations/?ordering=
-    Query parameter that orders the returned objects based on the provided field to order by.
+    **Example Usage**
+
+    [GET /api/locations/?search=johnson](/api/locations/?search=johnson&format=json)
+
+    Return all Location objects that have a field that matches the "johnson" string.
+
+    ### **Ordering**
+
+    Order the returned objects based on the provided field.
+
+    [GET /api/locations/?ordering=](/api/locations/?ordering=&format=json)
 
-    Additionally, you can query against any field you like:
+    **Example Usage**
 
-    ie.
-    GET /api/locations/?building=Johnson+Center
-    will return all Location objects located in the "Johnson Center" building.
+    [GET /api/locations/?ordering=building](/api/locations/?ordering=building&format=json)
+
+    Return all Location objects ordered by building name ascending.
+
+    [GET /api/locations/?ordering=-building](/api/locations/?ordering=-building&format=json)
+
+    Return all Location objects ordered by building name descending.
+
+    ### **Field filtering**
+
+    You can query directly against any field.
+
+    **Example Usage**
+
+    [GET /api/locations/?building=Johnson+Center](/api/locations/?building=Johnson+Center&format=json)
+
+    Return all Location objects located in the "Johnson Center" building.
     """
     # All model fields that are available for filtering
     FILTER_FIELDS = (
@@ -174,30 +272,67 @@ class FacilityViewSet(viewsets.ReadOnlyModelViewSet):
     """
     A Facility is some type of establishment that has a schedule of open hours and a location that serves a specific purpose that can be categorized.
 
-    GET /api/facilities/
-    Return all Facility objects. We additionally filter out stale special_schedules to reduce client side calculations.
+    ---
+
+    ## Default behavior
+
+    [GET /api/facilities/](/api/facilities/?format=json)
+
+    Return all Facility objects. Additionally, we filter out stale special_schedules to reduce client side calculations.
+
+    ## Built-in query parameters
+
+    ### **Search**
 
-    Built-in query parameters:
+    [GET /api/facilities/?search=](/api/facilities/?search=&format=json)
 
-    GET /api/facilities/?search=
     Query parameter that returns objects that match a keyword provided in the search.
 
-    GET /api/facilities/?ordering=
+    **Example Usage**
+
+    [GET /api/facilities/?search=south](/api/facilities/?search=south&format=json)
+
+    Return all Facility objects that have a field that matches the string "south".
+
+    ### **Ordering**
+
+    [GET /api/facilities/?ordering=](/api/facilities/?ordering=&format=json)
+
     Query parameter that orders the returned objects based on the provided field to order by.
 
-    Additionally, you can query against any field you like:
+    **Example Usage**
+
+    [GET /api/facilities/?ordering=facility_name](/api/facilities/?ordering=facility_name&format=json)
+
+    Return all Facility objects ordered by facility_name ascending.
+
+    [GET /api/facilities/?ordering=-facility_name](/api/facilities/?ordering=-facility_name&format=json)
+
+    Return all Facility objects ordered by facility_name descending.
+
+    ### **Field filtering**
+
+    You can query directly against any field.
+
+    **Example Usage**
 
-    ie.
-    GET /api/facilities/?facility_name=Southside
-    will return the Facility object that has "Southside" as its name.
+    [GET /api/facilities/?facility_name=Southside](/api/facilities/?facility_name=Southside&format=json)
 
-    Custom query parameters:
+    Return the Facility object that has "Southside" as its name.
 
-    GET /api/facilities/?open_now
-    Query parameter that only returns open Facility objects.
+    ## Custom query parameters
 
-    GET /api/facilities/?closed_now
-    Query parameter that only returns closed Facility objects.
+    ### **open_now**
+
+    [GET /api/facilities/?open_now](/api/facilities/?open_now&format=json)
+
+    Only return open Facility objects.
+
+    ### **closed_now**
+
+    [GET /api/facilities/?closed_now](/api/facilities/?closed_now&format=json)
+
+    Only return closed Facility objects.
     """
     # All model fields that are available for filtering
     FILTER_FIELDS = (
@@ -265,22 +400,56 @@ class ScheduleViewSet(viewsets.ModelViewSet):
     """
     A period of time between two dates that represents the beginning and end of a "schedule" or rather, a collection of open times for a facility.
 
-    GET /api/schedules/
+    ---
+
+    ## Default behavior
+
+    [GET /api/schedules/](/api/schedules/?format=json)
+
     Return all Schedule objects that have not expired. (ie. end_date is before today)
 
-    Built-in query parameters:
+    ## Built-in query parameters
+
+    ### **Search**
+
+    [GET /api/schedules/?search=](/api/schedules/?search=&format=json)
 
-    GET /api/schedules/?search=
     Query parameter that returns objects that match a keyword provided in the search.
 
-    GET /api/schedules/?ordering=
+    **Example Usage**
+
+    [GET /api/schedules/?search=south](/api/schedules/?search=south&format=json)
+
+    Return all Schedule objects that have a field matching the string "south".
+
+    ### **Ordering**
+
+    [GET /api/schedules/?ordering=](/api/schedules/?ordering=&format=json)
+
     Query parameter that orders the returned objects based on the provided field to order by.
 
-    Additionally, you can query against any field you like:
+    **Example Usage**
+
+    [GET /api/schedules/?ordering=name](/api/schedules/?ordering=name&format=json)
+
+    Return all Schedule objects ordered by name ascending.
+
+    [GET /api/schedules/?ordering=-name](/api/schedules/?ordering=-name&format=json)
+
+    [GET /api/schedules/?ordering=name](/api/schedules/?ordering=name&format=json)
+
+    Return all Schedule objects ordered by name ascending.
+    Return all Schedule objects ordered by name descending.
+
+    ### **Field filtering**
+
+    You can query directly against any field.
+
+    **Example Usage**
+
+    [GET /api/schedules/?name=southside_main](/api/schedules/?name=southside_main&format=json)
 
-    ie.
-    GET /api/schedules/?name=southside_main
-    will return the Schedule object that has "southside_main" as its name.
+    Return the Schedule object that has "southside_main" as its name.
     """
     # All model fields that are available for filtering
     FILTER_FIELDS = (

whats-open/settings/base.py

@@ -245,6 +245,7 @@ INSTALLED_APPS = (
     'rest_framework',
     'rest_framework_gis',
     'django_filters',
+    'crispy_forms',
 )
 
 """