Overhaul API documentation

README.rst

@@ -1,19 +1,20 @@
 Lazorse!
 ========
 
-Lazorse is a web-framework with a strong emphasis on extensibility and
-separation of various concerns into independant middleware layers.
-
-It includes middleware to route requests, coerce parameters, dispatch to handlers,
-and render a response.  
-It borrows heavily from `other`_ `awesome`_ nodejs 
-`web frameworks`_ but with a couple of twists designed to make writing 
-machine-consumable ReSTful APIs a little easier. Because it's all "just 
+Lazorse is a resource-oriented web-framework with a strong emphasis on
+extensibility and the separation of various concerns into independent
+middleware_ layers.
+
+It includes middleware to find a resource, coerce URL parameters, dispatch to
+HTTP method handlers, and render a response.  
+
+It borrows heavily from other_ awesome_ node.js `web frameworks`_ but with a
+couple of twists designed to make writing machine-consumable ReSTful APIs a little easier. Because it's all "just 
 middleware", you can also pull out and re-arrange the various pieces to better 
 suit the needs of your application.
 
-.. _uri template rfc: http://tools.ietf.org/html/draft-gregorio-uritemplate-07
-.. _web frameworks: http://expressjs.com
+.. _middleware: http://stephensugden.com/middleware_guide/
+.. _web frameworks: http://expressjs.com/
 .. _other: http://zappajs.org
 .. _awesome: https://github.com/kadirpekel/coffeemate
 

doc/_static/sidebar.js

@@ -10,7 +10,7 @@ $(document).ready(function() {
   var sectionNames = {}
   var sections = $('div.section').get().map(function (node) {
     node.yTop = yOffset(node)
-    var header = $(node).children('h1, h2').first()
+    var header = $(node).children('h1, h2, h3').first()
     node.yBottom = yOffset(header.get(0)) + header.outerHeight()
     sectionNames[node.id] = node
     return node
@@ -31,6 +31,7 @@ $(document).ready(function() {
   }
 
   function highlightSection(section) {
+    if (!section) return
     $(".currentsection").removeClass('currentsection')
     $(section).addClass('currentsection')
     $(".sphinxsidebar a[href='#" + section.id + "']")

doc/_templates/projectlinks.html

@@ -1,7 +1,6 @@
 <h3>Project Links</h3>
 <ul>
 {% block projectlinks %}
-<li><a href="{{ pathto(master_doc) }}">Documentation Index</a></li>
 <li><a href="http://github.com/BetSmartMedia/Lazorse">Source on Github</a></li>
 <li><a href="http://github.com/BetSmartMedia/Lazorse/tree/master/examples">Example Apps</a></li>
 {% endblock %}

doc/api.rst

@@ -2,5 +2,116 @@
 API documentation
 =================
 
-.. automodule:: lazorse
-   :members:
+Exported API
+============
+
+The main export is a function that takes a "builder" function and constructs a
+`LazyApp <#app-building>`_ instance with it::
+
+  lazorseApp = require('lazorse') ->
+    # Build your app here
+
+Or, if you'd rather get back a connect app ready for more ``.use()`` calls::
+
+  connectApp = require('lazorse').connect ->
+    # Again, build the app here
+
+Finally, if you'd rather start a server automatically after the app is built::
+
+  require('lazorse').server port: 1234, host: '0.0.0.0', ->
+    # A pattern is emerging...
+
+The rest of the API is made up of the methods on ``LazyApp`` which are available
+on ``@`` (``this``) to your builder function.
+
+App-building
+====================
+
+The builder function is called with it's ``@`` context set to the partially
+constructed ``LazyApp`` instance, it builds out the app by calling methods
+and/or modifying properties on ``@``
+
+App-building properties
+-----------------------
+
+The following properties on ``@`` can be set to alter default behaviours:
+
+``@indexPath``, ``@examplePath`` and ``@parameterPath``:
+  Prefixes for the location of the `default resources`_. You can disable
+  any of these resources by setting their path prefix to ``false``.
+
+  Defaults: ``'/'``, ``'/examples'``, ``'/parameters'``
+
+``@passErrors``
+  Setting this to ``true`` will cause unrecognized errors to be passed to
+  ``@next()`` by :meth:`lazorse::LazyApp.handleErrors`.
+
+  Default: false
+
+App-building methods
+-----------------------
+
+.. automethod:: lazorse::LazyApp.resource
+
+.. automethod:: lazorse::LazyApp.helper
+
+  Lazorse installs 4 default helpers into every app:
+
+    * ``@data`` - Use this as a callback to asynchronous functions that use the
+      ``callback(err, result)`` idiom.
+    * ``@ok`` - Sets ``@res.data`` and call @next unconditionally.
+    * ``@error`` - Given a constructor function or a name registered with
+      :meth:`error`, and additional constructor arguments, constructs an error
+      and passes it to ``@next``.
+    * ``@link`` - Return a URL path to a resource given it's shortName and
+      a template expansion context object.
+
+  These are added before the builder function is called, so it's possible
+  (though not recommended) to over-ride or remove them by modifying
+  ``@helpers``.
+
+.. automethod:: lazorse::LazyApp.coerce
+.. automethod:: lazorse::LazyApp.render
+.. automethod:: lazorse::LazyApp.error
+.. automethod:: lazorse::LazyApp.include
+.. automethod:: lazorse::LazyApp.before
+
+Middleware Methods
+==================
+
+These methods act as Connect middleware. They remain bound to the app so you
+can safely pass them to connects ``.use()`` method without wrapping them in a
+callback function.
+
+.. automethod:: lazorse::LazyApp.findResource
+.. automethod:: lazorse::LazyApp.coerceParams
+.. automethod:: lazorse::LazyApp.dispatchHandler
+.. automethod:: lazorse::LazyApp.renderResponse
+.. automethod:: lazorse::LazyApp.handleErrors
+
+Default Resources
+=================
+
+Lazorse adds three default resources to every app (unless they are disabled_):
+
+Index (default path ``/``):
+  Returns metadata for all of the *named* resources in the app, including URI
+  templates, descriptions, and supported HTTP methods, and links to example
+  requests if any are defined.
+
+Examples (default path ``/examples/{shortName}``):
+  Responds with an array of all of the example requests for the named resource.
+
+Parameters (default paths ``/parameters/`` and ``/parameters/{parameterName}``)
+  Responds with the documentation string for all, or the specifically named,
+  URL parameter coercions given to :meth:`lazorse::LazyApp.coerce`.
+
+.. _disabled:  #app-building-properties
+
+Request Contexts
+================
+
+Every request has a special `request context` assigned to it. This context is
+shared by all of the coercions, helpers, and handlers used in a single request.
+
+.. include:: handler_context.rst

doc/handler_context.rst

@@ -3,7 +3,7 @@ The context is made up of 2 objects in a delegation chain:
     1. An object containing URI Template variables, which delegates to:
     2. A request context object containing:
 
-       * All helpers defined for the app (using :meth:`lazorse::LazyApp.helper`)
+       * All helpers defined for the app using :meth:`~lazorse::LazyApp.helper`.
        * ``app``: The lazorse app
        * ``req``: The request object from node (via connect)
        * ``res``: The response object from node (via connect)