X-Git-Url: http://git.ithinksw.org/philo.git/blobdiff_plain/fb8a270fa22abc217efc471d860c76d5a2352c61..c79f6c48cae9411acf3f413b25d942df34f7719f:/philo/templatetags/embed.py

diff --git a/philo/templatetags/embed.py b/philo/templatetags/embed.py
index eb4cd68..9599240 100644
--- a/philo/templatetags/embed.py
+++ b/philo/templatetags/embed.py
@@ -1,7 +1,12 @@
+"""
+The embed template tags are automatically included as builtins if :mod:`philo` is an installed app.
+
+"""
 from django import template
-from django.contrib.contenttypes.models import ContentType
 from django.conf import settings
+from django.contrib.contenttypes.models import ContentType
 from django.template.loader_tags import ExtendsNode, BlockContext, BLOCK_CONTEXT_KEY, TextNode, BlockNode
+
 from philo.utils import LOADED_TEMPLATE_ATTR
 
 
@@ -286,11 +291,23 @@ def parse_content_type(bit, tagname):
 	return ct
 
 
-def do_embed(parser, token):
+@register.tag
+def embed(parser, token):
 	"""
-	The {% embed %} tag can be used in two ways:
-	{% embed <app_label>.<model_name> with <template> %} :: Sets which template will be used to render a particular model.
-	{% embed (<app_label>.<model_name> <object_pk> || <instance>) [<argname>=<value> ...] %} :: Embeds the instance specified by the given parameters in the document with the previously-specified template. Any kwargs provided will be passed into the context of the template.
+	The {% embed %} tag can be used in two ways.
+	
+	First, to set which template will be used to render a particular model. This declaration can be placed in a base template and will propagate into all templates that extend that template.
+	
+	Syntax::
+	
+		{% embed <app_label>.<model_name> with <template> %}
+	
+	Second, to embed a specific model instance in the document with a template specified earlier in the template or in a parent template using the first syntax. The instance can be specified as a content type and pk or as a context variable. Any kwargs provided will be passed into the context of the template.
+	
+	Syntax::
+	
+		{% embed (<app_label>.<model_name> <object_pk> || <instance>) [<argname>=<value> ...] %}
+	
 	"""
 	bits = token.split_contents()
 	tag = bits.pop(0)
@@ -330,7 +347,4 @@ def do_embed(parser, token):
 	except ValueError:
 		return EmbedNode(ct, object_pk=parser.compile_filter(pk), kwargs=kwargs)
 	else:
-		return ConstantEmbedNode(ct, object_pk=pk, kwargs=kwargs)
-
-
-register.tag('embed', do_embed)
\ No newline at end of file
+		return ConstantEmbedNode(ct, object_pk=pk, kwargs=kwargs)
\ No newline at end of file