Typography fixes (#18)

Typography fixes, inspired by Joni Trythall

docs/api_documentation.md

@@ -9,7 +9,7 @@ API documentation can be automatically created from EndpointSet method docstring
 ```python
 class AuthorEndpointSet(DjangoModelEndpointSetMixin, api.ResourceEndpointSet):
     ...
-    
+
     def retrieve(self, request, pk):
         """
         Identifier: Retrieve an author
@@ -54,7 +54,7 @@ class AuthorEndpointSet(DjangoModelEndpointSetMixin, api.ResourceEndpointSet):
                         "jsonapi": {"version": "1.0"},
                         "errors": [
                             {
-                                "detail": 'Author not found',
+                                "detail": "Author not found",
                                 "status": "404"
                             }
                         ]
@@ -77,7 +77,7 @@ class AuthorEndpointSet(DjangoModelEndpointSetMixin, api.ResourceEndpointSet):
 
 ### 2. Wire Up API Documentation
 
-pinax-api creates URL patterns for you automatically via the `doc_view()` utility. Serve automatic documentation at "/docs" by following this example:
+pinax-api creates URL patterns for you automatically via the `doc_view()` utility. Serve automatic documentation at `/docs` by following this example:
 
 ```python
 # urls.py

docs/authentication.md

@@ -4,15 +4,15 @@
 
 `api.EndpointSet` checks authentication at three levels of granularity in the following order, from most specific to most general:
 
-1. Endpoint authentication - This authentication applies to only the specified endpoint. Activated via endpoint `authentication` attribute.
-2. Class authentication - This authentication applies to the entire EndpointSet class. Activated via class `middleware["authentication"]` attribute.
-3. Django authentication - This authentication applies to the entire application. Straight from the pony's mouth using `self.request.user.is_authenticated` and the standard Django AUTHENTICATION_BACKENDS. 
+1. Endpoint authentication — This authentication applies to only the specified endpoint. Activated via endpoint `authentication` attribute.
+2. Class authentication — This authentication applies to the entire EndpointSet class. Activated via class `middleware["authentication"]` attribute.
+3. Django authentication — This authentication applies to the entire application. Straight from the pony's mouth using `self.request.user.is_authenticated` and the standard Django AUTHENTICATION_BACKENDS.
 
 If authentication fails or succeeds at any level, more general authentication checks are not processed.
 
 ### Writing An Authenticator Class
 
-`api.EndpointSet` authenticators are Python classes with an "authenticate" method. This method must accept one required parameter, a Request object. The "authenticate()" method should respond by either raising `AuthenticationFailed` or returning a user object (if authentication succeeded) or None (if authentication cannot be determined).
+`api.EndpointSet` authenticators are Python classes with an `.authenticate()` method. `.authenticate()` must accept a `Request` parameter and respond by either raising `AuthenticationFailed` or returning a user object (if authentication succeeded) or None (if authentication cannot be determined).
 
 NOTE: Do not confuse Django authentication backends (referenced in settings.py AUTHENTICATION_BACKENDS) with pinax-api authentication backends. Django authentication backends allow overriding `get_user()`, while pinax-api authentication backends have no such method.
 

docs/endpointset.md

@@ -43,7 +43,7 @@ class AuthorEndpointSet(api.ResourceEndpointSet):
     )
 ```
 
-Endpoints reference Author resources by a "pk" attribute, specified in `url.lookup["field"]`. The PK in this case is an integer primary key, specified by the `url.lookup["regex"]` regular expression.
+Endpoints reference Author resources by a `pk` attribute, specified in `url.lookup["field"]`. The PK in this case is an integer primary key, specified by the `url.lookup["regex"]` regular expression.
 
 This example results in two automatic URL paths for accessing endpoints:
 
@@ -60,17 +60,17 @@ Most JSON:API endpoints return an HttpResponse containing some form of JSON-seri
 >
 > - `links`: a [links object](http://jsonapi.org/format/#document-links) containing links related to the resource.
 
-and pinax-api always includes these links. However, `api.Resource` classes by themselves don't know anything about endpoints and URL paths. In order to provide this "self" URL link resolution, you must connect the Resource class with the ResourceEndpointSet class using `api.bind()`.
+and pinax-api always includes these links. However, `api.Resource` classes by themselves don't know anything about endpoints and URL paths. In order to provide self-reference endpoint link resolution, you must connect the Resource class with the ResourceEndpointSet class using `api.bind()`.
 
 **Bind Resource classes to EndpointSets to provide URL resolution for resource rendering.**
 
-pinax-api uses a "bound" ResourceEndpointSet to determine the URL patterns for a resource `self` link. Unbound resource classes do not contain any URL patterns and therefore cannot be rendered.
+pinax-api uses a “bound” ResourceEndpointSet to determine the URL patterns for a resource endpoint link. Unbound resource classes do not contain any URL patterns and therefore cannot be rendered.
 
 Binding a ResourceEndpointSet with a Resource class has three results:
 
-1. creates a new "bound" resource class which associates the original Resource class with the ResourceEndpointSet class
-2. adds a `resource_class` attribute to the ResourceEndpointSet, pointing to the new "bound" resource class
-3. registers the new "bound" resource class in the api registry
+1. creates a new “bound” resource class which associates the original Resource class with the ResourceEndpointSet class
+2. adds a `resource_class` attribute to the ResourceEndpointSet, pointing to the new “bound” resource class
+3. registers the new “bound” resource class in the api registry
 
 Bind a Resource class to a ResourceEndpointSet by decorating with `api.bind()`:
 
@@ -93,7 +93,7 @@ Your EndpointSet does not need to implement all possible endpoints, just the end
 
 ###### SHOW RESOURCE
 
-* `.list()` - show collection of resources
+* `.list()` — show collection of resources
 
   Use `.resource_class.from_queryset()` to render a collection of resources:
 
@@ -121,7 +121,7 @@ Your EndpointSet does not need to implement all possible endpoints, just the end
   ```
 
 
-* `.retrieve()` - show single resource
+* `.retrieve()` — show single resource
 
   Show a retrieved object:
 
@@ -133,7 +133,7 @@ Your EndpointSet does not need to implement all possible endpoints, just the end
 
 ###### CREATE / MODIFY RESOURCE
 
-* `.create()` - create new resource
+* `.create()` — create new resource
 
   Requires validation of user-provided data, automatically handled by `.validate()`. Use `.render_create()` for rendering a new resource:
 
@@ -145,7 +145,7 @@ Your EndpointSet does not need to implement all possible endpoints, just the end
   ```
 
 
-* `.update()` - update resource
+* `.update()` — update resource
 
   Requires validation of user-provided data, automatically handled by `.validate()`:
 
@@ -160,7 +160,7 @@ Your EndpointSet does not need to implement all possible endpoints, just the end
 
 ###### DESTROY RESOURCE
 
-* `.destroy()` - delete resource
+* `.destroy()` — delete resource
 
   Delete a retrieved object:
 
@@ -213,7 +213,7 @@ class AuthorResource(api.Resource):
     }
 ```
 
-validation would ignore the "email" and "phone" fields and only update the "name" attribute.
+validation would ignore the `email` and `phone` fields and only update the `name` attribute.
 
 ###### ContextManager
 
@@ -238,15 +238,15 @@ Resource rendering produces a JSON:API-compliant representation of resources, su
 
 > The response **MUST** also include a document that contains the primary resource...
 
-Rendering is usually the last task an endpoint performs. pinax-api provides three rendering methods for "success" responses:
+Rendering is usually the last task an endpoint performs. pinax-api provides three rendering methods for “success” responses:
 
-* `.render()` - return an HttpResponse with rendered resource instance (or collection of instances) based on existing, newly created, or updated data
-* `.render_create()` - return an HttpResponse with JSON:API-compliant payload for a newly created resource
-* `.render_delete()` - return an HttpResponse with no payload and 204 status_code
+* `.render()` — return an HttpResponse with rendered resource instance (or collection of instances) based on existing, newly created, or updated data
+* `.render_create()` — return an HttpResponse with JSON:API-compliant payload for a newly created resource
+* `.render_delete()` — return an HttpResponse with no payload and 204 status_code
 
-Standard endpoints instantiate a resource instance using `.resource_class()`, never by referencing the resource class directly. `.resource_class()` takes advantage of Resource - ResourceEndpointSet binding (see "Step Three: Bind ResourceEndpointSet To Resource Class" above) to determine the resource class.
+Standard endpoints instantiate a resource instance using `.resource_class()`, never by referencing the resource class directly. `.resource_class()` takes advantage of Resource–ResourceEndpointSet binding (see “Step Three: Bind ResourceEndpointSet To Resource Class” above) to determine the resource class.
 
-- `.resource_class()` - return the bound `api.Resource`-based resource class
+- `.resource_class()` — return the “bound” `api.Resource`-based resource class
 
 This is correct:
 
@@ -284,13 +284,13 @@ pinax-api will complain during `self.render()`:
 "AssertionError: resolve_url_kwargs requires a bound resource (got <myapp.resources.UserResource object at 0x10cf77d30>)."
 ```
 
-Resource rendering fails in this case because the Resource instance is not associated with an ResourceEndpointSet and therefore the resource "self" link required by JSON:API cannot be generated. Remember: **always render "bound" resources**.
+Resource rendering fails in this case because the Resource instance is not associated with an ResourceEndpointSet and therefore the resource endpoint reference link required by JSON:API cannot be generated. Remember: **always render “bound” resources**.
 
 ##### Returning Errors
 
 When your endpoint detects a problem, invoke `.render_error()`. If a `status` kwarg is not provided, `.render_error()` sets the response status_code to 400.
 
-- `.render_error(status=400)` - return an HttpResponse with error message and status code
+- `.render_error(status=400)` — return an HttpResponse with error message and status code
 
 ```python
 from pinax import api
@@ -349,10 +349,10 @@ class AuthorEndpointSet(api.DjangoModelEndpointSetMixin, api.ResourceEndpointSet
 
 `DjangoModelEndpointSetMixin` provides three new methods and overrides a fourth:
 
-* `.get_pk()` - return the PK value for the Django model object
-* `.get_resource_object_model()` - return the resource class underlying model
-* `.get_queryset()` - return QuerySet of all resource class underlying model instances
-* `.prepare()` - sets `self.pk` and `self.obj` if HTTP request method acts on single objects. Raises 404 if object is not found in queryset using specified PK.
+* `.get_pk()` — return the PK value for the Django model object
+* `.get_resource_object_model()` — return the resource class underlying model
+* `.get_queryset()` — return QuerySet of all resource class underlying model instances
+* `.prepare()` — sets `self.pk` and `self.obj` if HTTP request method acts on single objects. Raises 404 if object is not found in queryset using specified PK.
 
 ##### Resource Proxying
 

docs/getting_started.md

@@ -2,7 +2,7 @@
 
 ### Install `pinax-api`
 
-Add "pinax-api" to your project `requirements.txt` file or install pinax-api manually:
+Add `pinax-api` to your project `requirements.txt` file or install pinax-api manually:
 
 ```
 $ pip install pinax-api

docs/index.md

@@ -21,17 +21,17 @@
 
 ## Topic Guides
 
-[Resources](resources.md) - Exposing information
+[Resources](resources.md) — Exposing information
 
-[Relationships](relationships.md) - Connections between resources
+[Relationships](relationships.md) — Connections between resources
 
-[Endpoints](endpointset.md) - Creating and manipulating resources
+[Endpoints](endpointset.md) — Creating and manipulating resources
 
-[Authentication](authentication.md) - Is this user valid?
+[Authentication](authentication.md) — Is this user valid?
 
-[Permissions](permissions.md) - Is this user allowed access?
+[Permissions](permissions.md) — Is this user allowed access?
 
-[Automatic Documentation](api_documentation.md) - API documentation for developers
+[Automatic Documentation](api_documentation.md) — API documentation for developers
 
 ## References
 

docs/overview.md

@@ -15,7 +15,7 @@ Relationships connect resources to other resources. Relationships are similar to
 
 #### Endpoints
 
-Applications serve resources and relationships from methods (referred to as "endpoints") in an `api.EndpointSet`-based class. Each endpoint handles either creating, updating, retrieving, or deleting resources.
+Applications serve resources and relationships from methods (referred to as “endpoints”) in an `api.EndpointSet`-based class. Each endpoint handles either creating, updating, retrieving, or deleting resources.
 
 pinax-api provides two `EndpointSet`-based classes: `ResourceEndpointSet` and `RelationshipEndpointSet`. A ResourceEndpointSet manipulates resources, while a RelationshipEndpointSet manipulates resources related to another resource. See the [Endpoints topic guide](endpointset.md) for more details.
 
@@ -25,9 +25,9 @@ pinax-api manages authentication and permissions for `api.EndpointSet`-based cla
 
 When processing an HTTP request, pinax-api performs authentication and permissions checks in the following order:
 
-1. Authenticate User - is user authenticated?
-2. Prepare Data - obtain resource data, available for permissions check
-3. Check Permissions - does user have permission to access/manipulate this resource?
+1. Authenticate User — is user authenticated?
+2. Prepare Data — obtain resource data, available for permissions check
+3. Check Permissions — does user have permission to access/manipulate this resource?
 4. Invoke Endpoint
 
 If authentication, preparation, or permissions checks encounter an error, they raise an exception and the endpoint is not invoked.

docs/permissions.md

@@ -4,8 +4,8 @@
 
 pinax-api checks permissions at two levels of granularity, in the following order:
 
-1. Endpoint permissions - These permissions checks apply to only the specified endpoint. Activated via endpoint `permissions` attribute. 
-2. Class permissions - These permissions checks apply to the entire EndpointSet-based class. Activated via class `middleware["permissions"]` attribute. 
+1. Endpoint permissions — These permissions checks apply to only the specified endpoint. Activated via endpoint `permissions` attribute.
+2. Class permissions — These permissions checks apply to the entire EndpointSet-based class. Activated via class `middleware["permissions"]` attribute.
 
 If permissions checking fails or succeeds at any level, more general permission checking is not processed.
 
@@ -19,9 +19,9 @@ def my_perm_checker(request, endpointset):
     return ok, status, msg
 ```
 
-* ok - "user has permission", either True or False
-* status - HTTP status code integer - only used if permissions check fails
-* msg - error message string - only used if permissions check fails
+* ok — "user has permission", either True or False
+* status — HTTP status code integer, only used if permissions check fails
+* msg — error message string, only used if permissions check fails
 
 Here is a simple permissions check function:
 

docs/relationships.md

@@ -29,13 +29,13 @@ class AuthorResource(api.Resource):
     }
 ```
 
-This resource relates an Author to a collection of "authortag" resources, as well as a single "agent" resource. At the model level, this relationship might look like this:
+This resource relates an Author to a collection of `authortag` resources, as well as a single `agent` resource. At the model level, this relationship might look like this:
 
 ```python
 class Author(models.Model):
     name = models.CharField(max_length=100)
     agent = models.ForeignKey(Agent, null=True)
-    
+
 class AuthorTag(models.Model):
     label = models.CharField(max_length=50)
     author = models.ForeignKey(Author)
@@ -108,7 +108,7 @@ class AuthorEndpointSet(api.ResourceEndpointSet):
     }
 ```
 
-If a Resource HAS defined relationships and a ResourceEndpointSet DOES NOT, URL linkage for the related resource will not be generated. This does not violate the JSON:API [specification](http://jsonapi.org/format/#document-resource-objects) which states "relationships" are optional:
+If a Resource HAS defined relationships and a ResourceEndpointSet DOES NOT, URL linkage for the related resource will not be generated. This does not violate the JSON:API [specification](http://jsonapi.org/format/#document-resource-objects) which states `relationships` are optional:
 
 >In addition, a resource object **MAY** contain any of these top-level members:
 >
@@ -138,14 +138,14 @@ class AuthorTagCollectionEndpointSet(api.RelationshipEndpointSet):
 
 ##### Step Two: Create Relationship Endpoints
 
-Resource relationship retrieval and manipulation is performed by RelationshipEndpointSet methods, called "endpoints". These methods have specific names based on automatic HTTP method to URL mapping. See [URL Mapping](urlmapping.md) for more details.
+Resource relationship retrieval and manipulation is performed by RelationshipEndpointSet methods, called “endpoints”. These methods have specific names based on automatic HTTP method to URL mapping. See [URL Mapping](urlmapping.md) for more details.
 
 #### Supported Endpoints
 
-- `.retrieve()` - retrieve relationship members
-- `.create()` - add members to relationship (**does not** imply related-object creation)
-- `.update()` - replace relationship members (**does not** imply related-object update)
-- `.destroy()` - delete relationship members
+- `.retrieve()` — retrieve relationship members
+- `.create()` — add members to relationship (**does not** imply related-object creation)
+- `.update()` — replace relationship members (**does not** imply related-object update)
+- `.destroy()` — delete relationship members
 
 None of these methods should create or update resources, they should just change the relationship members for the resource. According to JSON:API [specification](http://jsonapi.org/format/#crud-updating-relationships) the only exception to this policy is `.destroy()`:
 
@@ -157,7 +157,7 @@ You may choose not to implement relationship endpoints even when relationships e
 
 If a relationship is correctly defined in the Resource and in the ResourceEndpointSet, the retrieved resource will contain URL links to the related resource. However, related resource requests will fail because no relationship endpoints exist.
 
-In our AuthorEndpointSet above, "tags" refers to `AuthorTagCollectionEndpointSet`. If you don't want relationship endpoints, simply define an empty RelationshipEndpointSet class:
+In our AuthorEndpointSet above, `tags` refers to `AuthorTagCollectionEndpointSet`. If you don't want relationship endpoints, simply define an empty RelationshipEndpointSet class:
 
 ```python
 from pinax import api