From ac6ebd8b38a46afb0b249574be71a276f95b6efa Mon Sep 17 00:00:00 2001
From: Stephen Burrows <stephen.r.burrows@gmail.com>
Date: Thu, 12 May 2011 16:54:47 -0400
Subject: [PATCH] Added docs for the db template loader and skeleton docs for
 templatetags.  Updated template tag references to actually point to
 templatetags. Made some minor improvements to references.

---
 docs/conf.py                         |  4 ++
 docs/index.rst                       |  4 +-
 docs/loaders.rst                     |  5 ++
 docs/models/entities.rst             |  2 +-
 docs/models/nodes-and-views.rst      |  2 +
 docs/templatetags.rst                | 74 ++++++++++++++++++++++++++++
 philo/loaders/database.py            |  4 ++
 philo/models/pages.py                | 14 +++---
 philo/templatetags/collections.py    |  5 +-
 philo/templatetags/containers.py     |  5 +-
 philo/templatetags/embed.py          | 13 +++--
 philo/templatetags/include_string.py |  6 ++-
 philo/templatetags/nodes.py          | 11 +++--
 13 files changed, 130 insertions(+), 19 deletions(-)
 create mode 100644 docs/loaders.rst
 create mode 100644 docs/templatetags.rst

diff --git a/docs/conf.py b/docs/conf.py
index 043219d..f32576a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -91,6 +91,10 @@ pygments_style = 'sphinx'
 #modindex_common_prefix = []
 
 
+# Autodoc config
+autodoc_member_order = "bysource"
+
+
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
diff --git a/docs/index.rst b/docs/index.rst
index 3575ddb..3e4b1e7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,10 +14,12 @@ Contents:
    intro
    models/intro
    exceptions
-   middleware
+   handling_requests
    signals
    validators
    utilities
+   templatetags
+   loaders
 
 Indices and tables
 ==================
diff --git a/docs/loaders.rst b/docs/loaders.rst
new file mode 100644
index 0000000..41c4cd9
--- /dev/null
+++ b/docs/loaders.rst
@@ -0,0 +1,5 @@
+Database Template Loader
+========================
+
+.. automodule:: philo.loaders.database
+	:members:
diff --git a/docs/models/entities.rst b/docs/models/entities.rst
index c311d59..d794c90 100644
--- a/docs/models/entities.rst
+++ b/docs/models/entities.rst
@@ -1,7 +1,7 @@
 Entities and Attributes
 =======================
 
-.. automodule:: philo.models.base
+.. module:: philo.models.base
 
 One of the core concepts in Philo is the relationship between the :class:`Entity` and :class:`Attribute` classes. :class:`Attribute`\ s represent an arbitrary key/value pair by having one :class:`GenericForeignKey` to an :class:`Entity` and another to an :class:`AttributeValue`.
 
diff --git a/docs/models/nodes-and-views.rst b/docs/models/nodes-and-views.rst
index b78dbd9..ab6dfb9 100644
--- a/docs/models/nodes-and-views.rst
+++ b/docs/models/nodes-and-views.rst
@@ -52,6 +52,8 @@ Pages
 .. autoclass:: Template
 	:members:
 	:show-inheritance:
+	
+	.. seealso:: :mod:`philo.loaders.database`
 
 .. autoclass:: Contentlet
 	:members:
diff --git a/docs/templatetags.rst b/docs/templatetags.rst
new file mode 100644
index 0000000..60224eb
--- /dev/null
+++ b/docs/templatetags.rst
@@ -0,0 +1,74 @@
+Template Tags
+=============
+
+.. automodule:: philo.templatetags
+
+Collections
++++++++++++
+
+.. automodule:: philo.templatetags.collections
+		
+	.. templatetag:: membersof
+	
+	membersof
+	---------
+	
+	Usage::
+	
+		{% membersof <collection> with <app_label>.<model_name> as <var> %}
+
+
+.. automodule:: philo.templatetags.containers
+
+	.. templatetag:: container
+	
+	container
+	---------
+	
+	Usage::
+	
+		{% container <name> [[references <app_label>.<model_name>] as <variable>] %}
+
+.. 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> ...] %}
+
+.. automodule:: philo.templatetags.include_string
+
+	.. templatetag:: include_string
+	
+	include_string
+	--------------
+	
+	Include a flat string by interpreting it as a template.
+	
+	Usage::
+	
+		{% include_string <template_code> %}
+
+.. 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>] %}
diff --git a/philo/loaders/database.py b/philo/loaders/database.py
index 71b93a6..4c9c379 100644
--- a/philo/loaders/database.py
+++ b/philo/loaders/database.py
@@ -6,6 +6,10 @@ from philo.models import Template
 
 
 class Loader(BaseLoader):
+	"""
+	:class:`philo.loaders.database.Loader` enables loading of template code from :class:`.Template`\ s. This would let :class:`.Template`\ s be used with ``{% include %}`` and ``{% extends %}`` tags, as well as any other features that use template loading.
+	
+	"""
 	is_usable=True
 	
 	def load_template_source(self, template_name, template_dirs=None):
diff --git a/philo/models/pages.py b/philo/models/pages.py
index 3ad05d8..ae64b4d 100644
--- a/philo/models/pages.py
+++ b/philo/models/pages.py
@@ -1,6 +1,6 @@
 # encoding: utf-8
 """
-:class:`Page`\ s are the most frequently used :class:`View` subclass. They define a basic HTML page and its associated content. Each :class:`Page` renders itself according to a :class:`Template`. The :class:`Template` may contain :ttag:`container <philo.templatetags.containers.do_container>` tags, which define related :class:`Contentlet`\ s and :class:`ContentReference`\ s for any page using that :class:`Template`.
+:class:`Page`\ s are the most frequently used :class:`.View` subclass. They define a basic HTML page and its associated content. Each :class:`Page` renders itself according to a :class:`Template`. The :class:`Template` may contain :ttag:`container` tags, which define related :class:`Contentlet`\ s and :class:`ContentReference`\ s for any page using that :class:`Template`.
 
 """
 
@@ -158,7 +158,7 @@ class Page(View):
 	
 	def get_containers(self):
 		"""
-		Returns the results :attr:`~Template.containers` for the related template. This is a tuple containing the specs of all :ttag:`containers <philo.templatetags.containers.do_container>` in the :class:`Template`'s code. The value will be cached on the instance so that multiple accesses will be less expensive.
+		Returns the results :attr:`~Template.containers` for the related template. This is a tuple containing the specs of all :ttag:`container`\ s in the :class:`Template`'s code. The value will be cached on the instance so that multiple accesses will be less expensive.
 		
 		"""
 		if not hasattr(self, '_containers'):
@@ -168,7 +168,7 @@ class Page(View):
 	
 	def render_to_string(self, request=None, extra_context=None):
 		"""
-		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 <philo.templatetags.containers.do_container>`-based functionality as is used for HTML.
+		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.
 		
 		"""
 		context = {}
@@ -226,9 +226,9 @@ class Contentlet(models.Model):
 	"""Represents a piece of content on a page. This content is treated as a secure :class:`~philo.models.fields.TemplateField`."""
 	#: The page which this :class:`Contentlet` is related to.
 	page = models.ForeignKey(Page, related_name='contentlets')
-	#: This represents the name of the container as defined by a :ttag:`container <philo.templatetags.containers.do_container>` tag.
+	#: This represents the name of the container as defined by a :ttag:`container` tag.
 	name = models.CharField(max_length=255, db_index=True)
-	#: A secure :class:`~philo.models.fields.TemplateField` holding the content for this :class:`Contentlet`. Note that actually using this field as a template requires use of the :ttag:`include_string <philo.templatetags.include_string.do_include_string>` template tag.
+	#: A secure :class:`~philo.models.fields.TemplateField` holding the content for this :class:`Contentlet`. Note that actually using this field as a template requires use of the :ttag:`include_string` template tag.
 	content = TemplateField()
 	
 	def __unicode__(self):
@@ -243,11 +243,11 @@ class ContentReference(models.Model):
 	"""Represents a model instance related to a page."""
 	#: The page which this :class:`ContentReference` is related to.
 	page = models.ForeignKey(Page, related_name='contentreferences')
-	#: This represents the name of the container as defined by a :ttag:`container <philo.templatetags.containers.do_container>` tag.
+	#: This represents the name of the container as defined by a :ttag:`container` tag.
 	name = models.CharField(max_length=255, db_index=True)
 	content_type = models.ForeignKey(ContentType, verbose_name='Content type')
 	content_id = models.PositiveIntegerField(verbose_name='Content ID', blank=True, null=True)
-	#: A :class:`GenericForeignKey` to a model instance. The content type of this instance is defined by the :ttag:`container <philo.templatetags.containers.do_container>` tag which defines this :class:`ContentReference`.
+	#: A :class:`GenericForeignKey` to a model instance. The content type of this instance is defined by the :ttag:`container` tag which defines this :class:`ContentReference`.
 	content = generic.GenericForeignKey('content_type', 'content_id')
 	
 	def __unicode__(self):
diff --git a/philo/templatetags/collections.py b/philo/templatetags/collections.py
index 38b3f91..80dc20d 100644
--- a/philo/templatetags/collections.py
+++ b/philo/templatetags/collections.py
@@ -23,7 +23,10 @@ class MembersofNode(template.Node):
 
 def do_membersof(parser, token):
 	"""
-	{% membersof <collection> with <app_label>.<model_name> as <var> %}
+	Usage::
+	
+		{% membersof <collection> with <app_label>.<model_name> as <var> %}
+	
 	"""
 	params=token.split_contents()
 	tag = params[0]
diff --git a/philo/templatetags/containers.py b/philo/templatetags/containers.py
index f6def0a..1e2ff80 100644
--- a/philo/templatetags/containers.py
+++ b/philo/templatetags/containers.py
@@ -61,7 +61,10 @@ class ContainerNode(template.Node):
 
 def do_container(parser, token):
 	"""
-	{% container <name> [[references <type>] as <variable>] %}
+	Usage::
+		
+		{% container <name> [[references <app_label>.<model_name>] as <variable>] %}
+	
 	"""
 	params = token.split_contents()
 	if len(params) >= 2:
diff --git a/philo/templatetags/embed.py b/philo/templatetags/embed.py
index 39b29e0..7345f89 100644
--- a/philo/templatetags/embed.py
+++ b/philo/templatetags/embed.py
@@ -289,9 +289,16 @@ def parse_content_type(bit, tagname):
 
 def do_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.
+	
+	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> ...] %}
+	
 	"""
 	bits = token.split_contents()
 	tag = bits.pop(0)
diff --git a/philo/templatetags/include_string.py b/philo/templatetags/include_string.py
index 260dcff..1de9ded 100644
--- a/philo/templatetags/include_string.py
+++ b/philo/templatetags/include_string.py
@@ -26,7 +26,11 @@ class IncludeStringNode(template.Node):
 def do_include_string(parser, token):
 	"""
 	Include a flat string by interpreting it as a template.
-	{% include_string <template_code> %}
+	
+	Usage::
+	
+		{% include_string <template_code> %}
+	
 	"""
 	bits = token.split_contents()
 	if len(bits) != 2:
diff --git a/philo/templatetags/nodes.py b/philo/templatetags/nodes.py
index 00d9764..a926f98 100644
--- a/philo/templatetags/nodes.py
+++ b/philo/templatetags/nodes.py
@@ -68,10 +68,13 @@ class NodeURLNode(template.Node):
 @register.tag(name='node_url')
 def do_node_url(parser, token):
 	"""
-	{% 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>]%}
+	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>] %}
+	
 	"""
 	params = token.split_contents()
 	tag = params[0]
-- 
2.20.1