docs: initial

README.rst

@@ -20,8 +20,8 @@ will be built in directly.
    :alt: Bitdeli badge
    :target: https://bitdeli.com/free
 
-purpose
-=======
+Purpose
+-------
 
 krankshaft was designed to make the frustrating and unnecessarily complicated
 parts of Web APIs simple and beautiful by default.  It's built in layers that
@@ -45,8 +45,8 @@ Goals:
 - suggests a pattern, but doesnt restrict you to it
 - secure by default
 
-example
-=======
+Example
+-------
 
 This is just a suggested file structure, there is no limitation here.
 
@@ -78,10 +78,8 @@ In ``app/urls.py``::
         url('^view/$', 'view'),
     )
 
-What more did you expect?
-
-resource example
-================
+Resource example
+----------------
 
 In ``app/api.py``::
 
@@ -193,8 +191,8 @@ This resource implementation should be ideal for _most_ situations, but you're
 free to reimplement parts or all of it.  It's meant only as a pattern you can
 follow and is not required by the framework at all.
 
-what works
-==========
+What works
+----------
 
 - simple authentication/authorization schemes (not OAuth at the moment)
 - serialization of primitive types respecting HTTP Accept Header
@@ -206,11 +204,18 @@ what works
 - deep data validation
 - Django ORM based Model Resource (with model serialization/deserialization)
 
-todo
-====
+Todo
+----
 
 - auto-documenting based on doc strings (plus bootstrap interactive UI)
 - caching
 - easy-etag support
 - flask support
 - OAuth (1 and 2)
+
+Resources
+---------
+
+- `Code <https://github.com/dlamotte/krankshaft>`_
+- `Docs <http://krankshaft.readthedocs.org/en/latest/>`_
+- `Issues <https://github.com/dlamotte/krankshaft/issues>`_

docs/api/api.rst

@@ -0,0 +1,5 @@
+krankshaft.api
+==============
+
+.. automodule:: krankshaft.api
+   :members:

docs/api/auth.rst

@@ -0,0 +1,5 @@
+krankshaft.auth
+===============
+
+.. automodule:: krankshaft.auth
+   :members:

docs/api/authn.rst

@@ -0,0 +1,5 @@
+krankshaft.authn
+================
+
+.. automodule:: krankshaft.authn
+   :members:

docs/api/authz.rst

@@ -0,0 +1,5 @@
+krankshaft.authz
+================
+
+.. automodule:: krankshaft.authz
+   :members:

docs/api/models.rst

@@ -0,0 +1,5 @@
+krankshaft.models
+================
+
+.. automodule:: krankshaft.models
+   :members:

docs/api/query.rst

@@ -0,0 +1,5 @@
+krankshaft.query
+================
+
+.. automodule:: krankshaft.query
+   :members:

docs/api/resource.rst

@@ -0,0 +1,5 @@
+krankshaft.resource
+===================
+
+.. automodule:: krankshaft.resource
+   :members:

docs/api/serializer.rst

@@ -0,0 +1,5 @@
+krankshaft.serializer
+=====================
+
+.. automodule:: krankshaft.serializer
+   :members:

docs/api/throttle.rst

@@ -0,0 +1,5 @@
+krankshaft.throttle
+===================
+
+.. automodule:: krankshaft.throttle
+   :members:

docs/api/util.rst

@@ -0,0 +1,5 @@
+krankshaft.util
+===============
+
+.. automodule:: krankshaft.util
+   :members:

docs/api/valid.rst

@@ -0,0 +1,5 @@
+krankshaft.valid
+================
+
+.. automodule:: krankshaft.valid
+   :members:

docs/conf.py

@@ -20,6 +20,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.dirname(os.path.abspath('.')))
 
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'tests.settings')
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

docs/index.rst

@@ -1,8 +1,3 @@
-.. krankshaft documentation master file, created by
-   sphinx-quickstart on Wed Nov 20 13:35:45 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 krankshaft
 ==========
 
@@ -12,9 +7,6 @@ Currently only supports Django, but designed to work for
 other frameworks with some modification.  At some point, other framework support
 will be built in directly.
 
-purpose
-=======
-
 krankshaft was designed to make the frustrating and unnecessarily complicated
 parts of Web APIs simple and beautiful by default.  It's built in layers that
 allow the programmer to easily opt-in/out of.  From "Expose this model via
@@ -24,187 +16,40 @@ basics as I need them".
 krankshaft is meant to be a framework to build Web APIs and grow with your
 application.
 
-Goals:
-
-- simple and concise
-- keep the simple things simple
-- enable complex APIs without getting in the way
-- HTTP return codes are important, dont abstract them away
-- fail early
-- performance
-- no global state
-- easily extendable
-- suggests a pattern, but doesnt restrict you to it
-- secure by default
-
-example
-=======
-
-This is just a suggested file structure, there is no limitation here.
-
-In ``app/apiv1.py``::
-
-    from django.conf import settings
-    from krankshaft import API
-
-    apiv1 = API('v1', debug=settings.DEBUG)
-
-In ``app/views.py``::
-
-    from app.apiv1 import apiv1 as api
-
-    @api
-    def view(request):
-        return api.serialize(request, 200, {
-            'key': 'value'
-        })
-
-At this point, you'll still need to wire up the common routing for your
-framework.  In Django, it looks something like this:
-
-In ``app/urls.py``::
-
-    from django.conf.urls import patterns, include, url
-
-    urlpatterns += patterns('app.views',
-        url('^view/$', 'view'),
-    )
-
-What more did you expect?
-
-resource example
-================
-
-In ``app/api.py``::
-
-    from django.conf import settings
-
-    api = API('v1', debug=settings.DEBUG)
-
-    @api(url='^model/(?P<id>\d+)/$')
-    class ModelResource(object):
-        def get(self, request, id):
-            ...
-
-        def put(self, request, id):
-            ...
-
-        def delete(self, request, id):
-            ...
-
-In ``app/urls.py``::
-
-    from django.conf.urls import patterns, include, url
-    from .api import api
-
-    urlpatterns = patterns('',
-        url('^api/', include(api.urls)),
-    )
+.. note::
 
-This enables clients to make GET/PUT/DELETE requests to the endpoint::
+   These docs are still very young and need a lot of work.  I'll be giving it
+   some much needed attention in the future.
 
-    /api/v1/model/<id>/
+Guide
+-----
 
-If a POST is made, the client will receive the proper 405 response with the
-Allow header set to GET, PUT, DELETE.
-
-You can customize resources even more.  You can define your own routing scheme::
-
-    class ModelResource(object):
-        ...
-        def route(self, request, id):
-            # this is approximately the default
-            try:
-                view = getattr(self, request.method.lower())
-
-            except AttributeError:
-                return api.response(request, 405)
-
-            else:
-                return view(request, id)
-
-Or setup urls and multiple routes::
-
-    class ModelResource(object):
-        ...
-
-        def get_list(self, request):
-            ...
-
-        def post_list(self, request):
-            ...
-
-        def put_list(self, request):
-            ...
-
-        def delete_list(self, request):
-            ...
-
-        def query(self, request):
-            if request.method != 'POST':
-                return api.response(request, 405, Allow='POST')
-            ...
-
-        def route(self, suffix, request, *args, **kwargs):
-            # this is approximately the default
-            try:
-                view = getattr(self, request.method.lower() + suffix)
-
-            except AttributeError:
-                return api.response(request, 405)
-
-            else:
-                return view(request, *args, **kwargs)
-
-        def route_list(self, request):
-            return self.route('_list', request)
-
-        def route_object(self, request, id):
-            return self.route('', request, id)
-
-        @property
-        def urls(self):
-            from django.conf.urls import patterns, url
-            return patterns('', [
-                url(r'^model/$', api.wrap(self.route_list)),
-                url(r'^model/query/$', api.wrap(self.query)),
-                url(r'^model/(?P<id>\d+)/$', api.wrap(self.route_object)),
-            ])
-
-Or (instead of building your own) use the one built in::
-
-    from krankshaft.resource import DjangoModelResource
-    from app.models import Model
-    from app.api import api
-
-    @api
-    class ModelResource(DjangoModelResource):
-        model = Model
-
-This resource implementation should be ideal for _most_ situations, but you're
-free to reimplement parts or all of it.  It's meant only as a pattern you can
-follow and is not required by the framework at all.
+.. toctree::
+   :maxdepth: 2
 
-what works
-==========
+   quickstart/index
 
-- simple authentication/authorization schemes (not OAuth at the moment)
-- serialization of primitive types respecting HTTP Accept Header
-- abort (raise-like http response return)
-- throttling
-- resource routing
-- query application (ie: ``?field__startswith=something&order_by=field``)
-  with pagination support
-- deep data validation
-- Django ORM based Model Resource (with model serialization/deserialization)
+API
+---
 
 .. toctree::
    :maxdepth: 2
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   api/api
+   api/auth
+   api/authn
+   api/authz
+   api/models
+   api/query
+   api/resource
+   api/serializer
+   api/throttle
+   api/util
+   api/valid
+
+Resources
+---------
+
+- `Code <https://github.com/dlamotte/krankshaft>`_
+- `Docs <http://krankshaft.readthedocs.org/en/latest/>`_
+- `Issues <https://github.com/dlamotte/krankshaft/issues>`_