Finishing models documentation

Author: Colton Provias

CHANGES.md

@@ -1,10 +1,11 @@
 # SQLAlchemy-JSONAPI Changelog
 
-## 1.0.0 - 1.0 Compatibility
+## 1.0.0 - Start of 1.0 Compatibility
 
 *In Development*
 
 * BREAKING Complete rewrite for JSON API 1.0 compatibility
+* Switching to Semantic Versioning
 
 ## 0.2 - Querying and View Permissions
 

README.md

@@ -1,5 +1,15 @@
-# sqlalchemy-jsonapi
+# SQLAlchemy-JSONAPI
 
-[JSON API](http://jsonapi.org/) implementation for use with [SQLAlchemy](http://www.sqlalchemy.org/).
+[JSON API](http://jsonapi.org/) implementation for use with
+[SQLAlchemy](http://www.sqlalchemy.org/).
 
-**CRITICAL: This version is in complete redevelopment to include 1.0 compatibility, permission checks, custom descriptors, etc.  Do not use in production unless you have a masochistic side.**
+SQLAlchemy-JSONAPI aims to implement the JSON API spec and to make it as simple
+to use and implement as possible.
+
+* [Documentation](http://sqlalchemy-jsonapi.readthedocs.org)
+
+# Installation
+
+```shell
+pip install sqlalchemy-jsonapi
+```

docs/models.rst

@@ -23,6 +23,8 @@ know, and it's quite useful!
 Attribute Descriptors
 =====================
 
+Sometimes, you may need to provide your own getters and setters to attributes::
+
         from sqlalchemy_jsonapi import attr_descriptor, AttributeActions
 
         class User(Base):
@@ -37,8 +39,56 @@ Attribute Descriptors
             def id_setter(self, new_id):
                 self.id = UUID(new_id)
 
+Note: id is not able to be altered after initial setting in JSON API to keep it
+consistent.
+
 Relationship Descriptors
 ========================
 
+Relationship's come in two flavors: to-one and to-many (or tranditional and
+LDS-flavored if you prefer those terms).  To one descriptors have the actions
+GET and SET::
+
+        @rel_descriptor(RelationshipActions.GET, 'significant_other')
+        def getter(self):
+            # ...
+
+        @rel_descriptor(RelationshipActions.SET, 'significant_other')
+        def setter(self, value):
+            # ...
+
+To-many have GET, APPEND, and DELETE::
+
+        @rel_descriptor(RelationshipActions.GET, 'angry_exes')
+        def getter(self):
+            # ...
+
+        @rel_descriptor(RelationshipActions.APPEND, 'angry_exes')
+        def appender(self):
+            # ...
+
+        @rel_descriptor(RelationshipActions.DELETE, 'angry_exes')
+        def remover(self):
+            # ...
+
+
 Permission Testing
-==================
+==================
+
+Permissions are a complex challenge in relational databases.  While the
+solution provided right now is extremely simple, it is almost guaranteed to
+evolve and change drastically as this library gets used more in production.
+Thus it is advisable that on every major version number increment, you should
+check this section for changes to permissions.
+
+Anyway, there are currently four permissions that are checked: GET, CREATE,
+EDIT, and DELETE. Permission tests can be applied module-wide or to specific
+fields::
+
+        @permission_test(Permissions.VIEW)
+        def can_view(self):
+            return self.is_published
+
+        @permission_test(Permissions.EDIT, 'slug')
+        def can_edit_slug(self):
+            return False