A few tweaks to the documentation

docs/helpers.rst

@@ -0,0 +1,49 @@
+=======
+Helpers
+=======
+
+AsTag
+=====
+
+.. currentmodule:: ttag.helpers
+
+.. class:: AsTag
+
+    Assists with the common case of tags which want to add something to the
+    context.
+
+    For example, if you wanted a tag which would add a QuerySet containing a
+    user's friends to the context (``{% get_friends user as friends %}``)::
+
+        class GetName(ttag.helpers.AsTag)
+            user = ttag.Arg()
+
+            def output(self, data, context):
+                return data['user'].friends_set.all()
+
+    Some additional customization attributes to those which are provided in the
+    standard ``Tag``'s :attr:`~ttag.Tag.Meta` class are available:
+
+    .. class:: Meta
+
+        .. attribute:: as_name
+
+            Use some other argument name rather than the default of ``as``.
+
+        .. attribute:: as_required
+
+            Set whether or not ``as varname`` argument is required
+            (defaults to ``True``).
+
+    Two additional methods of interest are ``as_value``, which allows you to
+    more completely customise output.
+
+    .. method:: as_value(self, data, context)
+
+        Returns the value you want to put into the context variable.
+        By default, returns the value of :meth:`~ttag.Tag.output`.
+
+    .. method::  as_output(self, data, context)
+
+        Returns the data you want to render when ``as varname`` is used.
+        Defaults to ``''``.

docs/index.rst

@@ -17,4 +17,5 @@ application.
 
    install
    usage
+   helpers
    reference

docs/usage.rst

@@ -155,29 +155,55 @@ arguments.
    define arguments and show an example
 
 
-Altering context
-================
+Using context
+=============
 
-.. todo::
+The :meth:`~ttag.Tag.output` method which we have used so far is just a
+shortcut the :meth:`~ttag.Tag.render`.
+
+The shortcut method doesn't provide direct access to the context, so if you
+need alter the context, or check other context variables, you can use
+:meth:`~ttag.Tag.render` directly.
+
+.. note:: The :class:`ttag.helpers.AsTag` class is available for the common
+          case of tags that end in ``... as something %}``. 
+
+For example::
+
+    class GetHost(ttag.Tag):
+        """
+        Returns the current host. Requires that ``request`` is on the template
+        context.
+        """
+
+        def render(self, context):
+            print context['request'].get_host()
 
-   explain that output() is a ust shortcut and that render() can be used
-   (with resolve()).
+Use :meth:`~ttag.Tag.resolve` to resolve the tag's arguments into a data
+dictionary::
 
-   Perhaps use the common 'as var' as the example.
+    class Welcome(ttag.Tag):
+        user = ttag.Arg()
+
+        def render(self, context):
+            context['welcomed'] = True
+            data = self.resolve(context)
+            name = data['user'].get_full_name()
+            return "Hi, %s!" % name
 
 
 Cleaning arguments
 ==================
 
-.. todo::
-
-   You can validate / clean arguments similar to Forms.
+You can validate / clean arguments similar to Django's forms.
 
-   ``clean_[argname](value)`` (must return the cleaned value)
+To clean an individual argument, use a ``clean_[argname](value)`` method.
+Ensure that your method returns the cleaned value.
 
-   ``clean(data)`` (must returned the cleaned data dictionary)
+After the individual arguments are cleaned, a ``clean(data)`` method is run.
+This method must return the cleaned data dictionary.
 
-   Use the ``ttag.TagValidationError`` exception to raise validation errors.
+Use the ``ttag.TagValidationError`` exception to raise validation errors.
 
 
 Writing a block tag