From 46997a51ed0ceb16ddbac712fbcb552a86cdc9e2 Mon Sep 17 00:00:00 2001
From: Stephen Burrows <stephen.r.burrows@gmail.com>
Date: Fri, 13 May 2011 13:22:11 -0400
Subject: [PATCH] Moved templatetag docs into the respective modules and
 fleshed them out. Centralized adding of template tags to builtins. Added
 __all__ declarations to philo.models.*. Added a bit of documentation to
 Page.render_to_string about context variables.

---
 docs/models/entities.rst             |  1 +
 docs/templatetags.rst                | 67 +++++-----------------------
 philo/models/__init__.py             | 14 ++++--
 philo/models/base.py                 |  3 ++
 philo/models/collections.py          |  5 ++-
 philo/models/nodes.py                |  5 ++-
 philo/models/pages.py                | 10 +++--
 philo/templatetags/collections.py    | 20 +++++++--
 philo/templatetags/containers.py     | 20 +++++++--
 philo/templatetags/embed.py          | 34 ++++++++++----
 philo/templatetags/include_string.py | 24 +++++-----
 philo/templatetags/nodes.py          | 29 +++++++++---
 12 files changed, 135 insertions(+), 97 deletions(-)

diff --git a/docs/models/entities.rst b/docs/models/entities.rst
index d794c90..20a6e80 100644
--- a/docs/models/entities.rst
+++ b/docs/models/entities.rst
@@ -16,6 +16,7 @@ Attributes
 	:members:
 
 .. automodule:: philo.models.base
+	:noindex:
 	:members: attribute_value_limiter
 
 .. autoclass:: JSONValue
diff --git a/docs/templatetags.rst b/docs/templatetags.rst
index 60224eb..97f0c56 100644
--- a/docs/templatetags.rst
+++ b/docs/templatetags.rst
@@ -7,68 +7,25 @@ Collections
 +++++++++++
 
 .. automodule:: philo.templatetags.collections
-		
-	.. templatetag:: membersof
-	
-	membersof
-	---------
-	
-	Usage::
-	
-		{% membersof <collection> with <app_label>.<model_name> as <var> %}
 
 
-.. automodule:: philo.templatetags.containers
+Containers
+++++++++++
 
-	.. templatetag:: container
-	
-	container
-	---------
-	
-	Usage::
-	
-		{% container <name> [[references <app_label>.<model_name>] as <variable>] %}
+.. automodule:: philo.templatetags.containers
 
-.. automodule:: philo.templatetags.embed
 
-	.. templatetag:: embed
-	
-	embed
-	-----
-	
-	The {% embed %} tag can be used in two ways.
-	
-	To set which template will be used to render a particular model::
-	
-		{% embed <app_label>.<model_name> with <template> %}
-	
-	To embed 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)::
-	
-		{% embed (<app_label>.<model_name> <object_pk> || <instance>) [<argname>=<value> ...] %}
+Embedding
++++++++++
 
-.. automodule:: philo.templatetags.include_string
+.. automodule:: philo.templatetags.embed
 
-	.. templatetag:: include_string
-	
-	include_string
-	--------------
-	
-	Include a flat string by interpreting it as a template.
-	
-	Usage::
-	
-		{% include_string <template_code> %}
+Nodes
++++++
 
 .. automodule:: philo.templatetags.nodes
 
-	.. templatetag:: node_url
-	
-	node_url
-	--------
-	
-	Usage::
-	
-		{% node_url [for <node>] [as <var>] %}
-		{% node_url with <obj> [for <node>] [as <var>] %}
-		{% node_url <view_name> [<arg1> [<arg2> ...] ] [for <node>] [as <var>] %}
-		{% node_url <view_name> [<key1>=<value1> [<key2>=<value2> ...] ] [for <node>] [as <var>] %}
+String inclusion
+++++++++++++++++
+
+.. automodule:: philo.templatetags.include_string
diff --git a/philo/models/__init__.py b/philo/models/__init__.py
index 523f789..3942b84 100644
--- a/philo/models/__init__.py
+++ b/philo/models/__init__.py
@@ -1,12 +1,20 @@
+from django.conf import settings
+from django.contrib.auth.models import User, Group
+from django.contrib.sites.models import Site
+
 from philo.models.base import *
 from philo.models.collections import *
 from philo.models.nodes import *
 from philo.models.pages import *
-from django.contrib.auth.models import User, Group
-from django.contrib.sites.models import Site
 
 
 register_value_model(User)
 register_value_model(Group)
 register_value_model(Site)
-register_templatetags('philo.templatetags.embed')
\ No newline at end of file
+
+if 'philo' in settings.INSTALLED_APPS:
+	from django.template import add_to_builtins
+	add_to_builtins('philo.templatetags.embed')
+	add_to_builtins('philo.templatetags.containers')
+	add_to_builtins('philo.templatetags.collections')
+	add_to_builtins('philo.templatetags.nodes')
\ No newline at end of file
diff --git a/philo/models/base.py b/philo/models/base.py
index 9533628..46fa8d5 100644
--- a/philo/models/base.py
+++ b/philo/models/base.py
@@ -16,6 +16,9 @@ from philo.utils.entities import AttributeMapper, TreeAttributeMapper
 from philo.validators import json_validator
 
 
+__all__ = ('Tag', 'value_content_type_limiter', 'register_value_model', 'unregister_value_model', 'JSONValue', 'ForeignKeyValue', 'ManyToManyValue', 'Attribute', 'Entity', 'TreeEntity')
+
+
 class Tag(models.Model):
 	"""A simple, generic model for tagging."""
 	#: A CharField (max length 255) which contains the name of the tag.
diff --git a/philo/models/collections.py b/philo/models/collections.py
index 7c773b3..be7b706 100644
--- a/philo/models/collections.py
+++ b/philo/models/collections.py
@@ -1,12 +1,14 @@
 from django.contrib.contenttypes import generic
 from django.contrib.contenttypes.models import ContentType
 from django.db import models
-from django.template import add_to_builtins as register_templatetags
 
 from philo.models.base import value_content_type_limiter, register_value_model
 from philo.utils import fattr
 
 
+__all__ = ('Collection', 'CollectionMember')
+
+
 class Collection(models.Model):
 	"""
 	Collections are curated ordered groupings of arbitrary models.
@@ -73,5 +75,4 @@ class CollectionMember(models.Model):
 		app_label = 'philo'
 
 
-register_templatetags('philo.templatetags.collections')
 register_value_model(Collection)
\ No newline at end of file
diff --git a/philo/models/nodes.py b/philo/models/nodes.py
index f29545a..58adb6e 100644
--- a/philo/models/nodes.py
+++ b/philo/models/nodes.py
@@ -8,7 +8,6 @@ from django.core.servers.basehttp import FileWrapper
 from django.core.urlresolvers import resolve, clear_url_caches, reverse, NoReverseMatch
 from django.db import models
 from django.http import HttpResponse, HttpResponseServerError, HttpResponseRedirect, Http404
-from django.template import add_to_builtins as register_templatetags
 from django.utils.encoding import smart_str
 
 from philo.exceptions import MIDDLEWARE_NOT_CONFIGURED, ViewCanNotProvideSubpath, ViewDoesNotProvideSubpaths
@@ -19,6 +18,9 @@ from philo.utils.entities import LazyPassthroughAttributeMapper
 from philo.signals import view_about_to_render, view_finished_rendering
 
 
+__all__ = ('Node', 'View', 'MultiView', 'Redirect', 'File')
+
+
 _view_content_type_limiter = ContentTypeSubclassLimiter(None)
 
 
@@ -387,5 +389,4 @@ class File(View):
 		return self.file.name
 
 
-register_templatetags('philo.templatetags.nodes')
 register_value_model(Node)
\ No newline at end of file
diff --git a/philo/models/pages.py b/philo/models/pages.py
index ae64b4d..bdd9b42 100644
--- a/philo/models/pages.py
+++ b/philo/models/pages.py
@@ -10,7 +10,7 @@ from django.contrib.contenttypes import generic
 from django.core.exceptions import ValidationError
 from django.db import models
 from django.http import HttpResponse
-from django.template import TemplateDoesNotExist, Context, RequestContext, Template as DjangoTemplate, add_to_builtins as register_templatetags, TextNode, VariableNode
+from django.template import TemplateDoesNotExist, Context, RequestContext, Template as DjangoTemplate, TextNode, VariableNode
 from django.template.loader_tags import BlockNode, ExtendsNode, BlockContext
 from django.utils.datastructures import SortedDict
 
@@ -23,6 +23,9 @@ from philo.utils import fattr
 from philo.validators import LOADED_TEMPLATE_ATTR
 
 
+__all__ = ('Template', 'Page', 'Contentlet', 'ContentReference')
+
+
 class LazyContainerFinder(object):
 	def __init__(self, nodes, extends=False):
 		self.nodes = nodes
@@ -170,6 +173,8 @@ class Page(View):
 		"""
 		In addition to rendering as an :class:`HttpResponse`, a :class:`Page` can also render as a string. This means, for example, that :class:`Page`\ s can be used to render emails or other non-HTML content with the same :ttag:`container`-based functionality as is used for HTML.
 		
+		The :class:`Page` will add itself to the context as ``page`` and its :attr:`~.Entity.attributes` as ``attributes``. If a request is provided, then :class:`request.node <.Node>` will also be added to the context as ``node`` and ``attributes`` will be set to the result of calling :meth:`~.View.attributes_with_node` with that :class:`.Node`.
+		
 		"""
 		context = {}
 		context.update(extra_context or {})
@@ -258,8 +263,5 @@ class ContentReference(models.Model):
 		app_label = 'philo'
 
 
-register_templatetags('philo.templatetags.containers')
-
-
 register_value_model(Template)
 register_value_model(Page)
\ No newline at end of file
diff --git a/philo/templatetags/collections.py b/philo/templatetags/collections.py
index 80dc20d..62d6138 100644
--- a/philo/templatetags/collections.py
+++ b/philo/templatetags/collections.py
@@ -1,3 +1,19 @@
+"""
+The collection template tags are automatically included as builtins if :mod:`philo` is an installed app.
+
+.. templatetag:: membersof
+
+membersof
+---------
+
+Given a collection and a content type, sets the results of :meth:`collection.members.with_model <.CollectionMemberManager.with_model>` as a variable in the context.
+
+Usage::
+
+	{% membersof <collection> with <app_label>.<model_name> as <var> %}
+
+"""
+
 from django import template
 from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
@@ -23,9 +39,7 @@ class MembersofNode(template.Node):
 
 def do_membersof(parser, token):
 	"""
-	Usage::
-	
-		{% membersof <collection> with <app_label>.<model_name> as <var> %}
+	{% membersof <collection> with <app_label>.<model_name> as <var> %}
 	
 	"""
 	params=token.split_contents()
diff --git a/philo/templatetags/containers.py b/philo/templatetags/containers.py
index 1e2ff80..722f2d8 100644
--- a/philo/templatetags/containers.py
+++ b/philo/templatetags/containers.py
@@ -1,3 +1,19 @@
+"""
+The container template tags are automatically included as builtins if :mod:`philo` is an installed app.
+
+.. templatetag:: container
+
+container
+---------
+
+If a template using this tag is used to render a :class:`.Page`, that :class:`.Page` will have associated content which can be set in the admin interface. If a content type is referenced, then a :class:`.ContentReference` object will be created; otherwise, a :class:`.Contentlet` object will be created.
+
+Usage::
+
+	{% container <name> [[references <app_label>.<model_name>] as <variable>] %}
+
+"""
+
 from django import template
 from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
@@ -61,9 +77,7 @@ class ContainerNode(template.Node):
 
 def do_container(parser, token):
 	"""
-	Usage::
-		
-		{% container <name> [[references <app_label>.<model_name>] as <variable>] %}
+	{% container <name> [[references <app_label>.<model_name>] as <variable>] %}
 	
 	"""
 	params = token.split_contents()
diff --git a/philo/templatetags/embed.py b/philo/templatetags/embed.py
index 7345f89..20e04a4 100644
--- a/philo/templatetags/embed.py
+++ b/philo/templatetags/embed.py
@@ -1,3 +1,26 @@
+"""
+The embed template tags are automatically included as builtins if :mod:`philo` is an installed app.
+
+.. templatetag:: embed
+
+embed
+-----
+
+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> ...] %}
+
+"""
 from django import template
 from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
@@ -289,15 +312,8 @@ def parse_content_type(bit, tagname):
 
 def do_embed(parser, token):
 	"""
-	The {% embed %} tag can be used in two ways.
-	
-	To set which template will be used to render a particular model::
-	
-		{% embed <app_label>.<model_name> with <template> %}
-	
-	To embed 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)::
-	
-		{% embed (<app_label>.<model_name> <object_pk> || <instance>) [<argname>=<value> ...] %}
+	{% embed <app_label>.<model_name> with <template> %}
+	{% embed (<app_label>.<model_name> <object_pk> || <instance>) [<argname>=<value> ...] %}
 	
 	"""
 	bits = token.split_contents()
diff --git a/philo/templatetags/include_string.py b/philo/templatetags/include_string.py
index 1de9ded..ecf9b45 100644
--- a/philo/templatetags/include_string.py
+++ b/philo/templatetags/include_string.py
@@ -1,3 +1,17 @@
+"""
+.. templatetag:: include_string
+
+include_string
+--------------
+
+Include a flat string by interpreting it as a template. The compiled template will be rendered with the current context.
+
+Usage::
+
+	{% include_string <template_code> %}
+
+"""
+
 from django import template
 from django.conf import settings
 
@@ -6,8 +20,6 @@ register = template.Library()
 
 
 class IncludeStringNode(template.Node):
-	"""The passed variable is expected to be a string of template code to be rendered with
-	the current context."""
 	def __init__(self, string):
 		self.string = string
 	
@@ -24,14 +36,6 @@ class IncludeStringNode(template.Node):
 
 
 def do_include_string(parser, token):
-	"""
-	Include a flat string by interpreting it as a template.
-	
-	Usage::
-	
-		{% include_string <template_code> %}
-	
-	"""
 	bits = token.split_contents()
 	if len(bits) != 2:
 		raise TemplateSyntaxError("%r tag takes one argument: the template string to be included" % bits[0])
diff --git a/philo/templatetags/nodes.py b/philo/templatetags/nodes.py
index a926f98..1d095bc 100644
--- a/philo/templatetags/nodes.py
+++ b/philo/templatetags/nodes.py
@@ -1,3 +1,22 @@
+"""
+The node template tags are automatically included as builtins if :mod:`philo` is an installed app.
+
+.. templatetag:: node_url
+
+node_url
+--------
+
+The :ttag:`node_url` tag allows access to :meth:`.View.reverse` from a template for a :class:`.Node`. By default, the :class:`.Node` that is used for the call is pulled from the context variable ``node``; however, this can be overridden with the ``[for <node>]`` option.
+
+Usage::
+
+	{% node_url [for <node>] [as <var>] %}
+	{% node_url with <obj> [for <node>] [as <var>] %}
+	{% node_url <view_name> [<arg1> [<arg2> ...] ] [for <node>] [as <var>] %}
+	{% node_url <view_name> [<key1>=<value1> [<key2>=<value2> ...] ] [for <node>] [as <var>] %}
+
+"""
+
 from django import template
 from django.conf import settings
 from django.contrib.sites.models import Site
@@ -68,12 +87,10 @@ class NodeURLNode(template.Node):
 @register.tag(name='node_url')
 def do_node_url(parser, token):
 	"""
-	Usage::
-	
-		{% node_url [for <node>] [as <var>] %}
-		{% node_url with <obj> [for <node>] [as <var>] %}
-		{% node_url <view_name> [<arg1> [<arg2> ...] ] [for <node>] [as <var>] %}
-		{% node_url <view_name> [<key1>=<value1> [<key2>=<value2> ...] ] [for <node>] [as <var>] %}
+	{% node_url [for <node>] [as <var>] %}
+	{% node_url with <obj> [for <node>] [as <var>] %}
+	{% node_url <view_name> [<arg1> [<arg2> ...] ] [for <node>] [as <var>] %}
+	{% node_url <view_name> [<key1>=<value1> [<key2>=<value2> ...] ] [for <node>] [as <var>] %}
 	
 	"""
 	params = token.split_contents()
-- 
2.20.1