Updated docs adding usage in templates and rendered

jazzband · Sep 4, 2011 · c676fc1 · c676fc1
1 parent fdbb084
commit c676fc1
Show file tree

Hide file tree

Showing 17 changed files with 196 additions and 67 deletions.
diff --git a/doc_src/usage.rst b/doc_src/usage.rst
@@ -2,12 +2,29 @@
 Using categories in templates
 =============================
 
-To use the template tags:::
+
+Getting all items within a category
+===================================
+
+The :py:class:`Category` model automatically gets `reverse relationships <https://docs.djangoproject.com/en/1.3/topics/db/queries/#following-relationships-backward>`_ with all other models related to it.
+
+This allows you access to the related objects from the template without altering any views. For example, if you only had ``Entry`` models related to :py:class:`Category`, your ``categories/category_detail.html`` template could look like
+
+.. literalinclude:: usage_example_template.html
+   :language: django
+   :linenos:
+
+
+If you have ``related_name`` parameters to the configuration (see :ref:`registering_models`), then you would use ``category.related_name.all`` instead of ``category.relatedmodel_set.all``\ .
+
+
+Template Tags
+=============
+
+To use the template tags::
 
 	{% import category_tags %}
 
-Filters
-*******
 
 ``tree_info``
 -------------
@@ -41,4 +58,5 @@ comma-separated list of feature names. The valid feature names are:
 
          Books                    ->  []
             Sci-fi                ->  [u'Books']
-               Dystopian Futures  ->  [u'Books', u'Sci-fi']
+               Dystopian Futures  ->  [u'Books', u'Sci-fi']
+
diff --git a/doc_src/usage_example_template.html b/doc_src/usage_example_template.html
@@ -0,0 +1,28 @@
+{% extends 'categories/base.html' %}
+{% block content %}
+<h1>{{ category }}</h1>
+{% if category.parent %}
+    <h2>Go up to 
+        <a href="{{ category.parent.get_absolute_url }}">
+            {{ category.parent }}
+        </a></h2>
+{% endif %}
+{% if category.description %}<p>{{ category.description }}</p>{% endif %}
+{% if category.children.count %}
+    <h2>Subcategories</h2>
+    <ul>
+        {% for child in category.children.all %}
+        <li><a href="{{ child.get_absolute_url }}">{{ child }}</a></li>
+        {% endfor %}
+    </ul>
+{% endif %}
+<h2>Entries</h2>
+{% if category.entries_set.all %}
+    {% for entry in category.entries_set.all %}
+        <p><a href="{{ entry.get_absolute_url }}">{{ entry.headline }}</a></p>
+    {% endfor %}
+{% else %}
+    <p><em>No entries for {{ category }}</em></p>
+{% endif %}
+
+{% endblock %}
diff --git a/docs/_sources/usage.txt b/docs/_sources/usage.txt
@@ -2,12 +2,29 @@
 Using categories in templates
 =============================
 
-To use the template tags:::
+
+Getting all items within a category
+===================================
+
+The :py:class:`Category` model automatically gets `reverse relationships <https://docs.djangoproject.com/en/1.3/topics/db/queries/#following-relationships-backward>`_ with all other models related to it.
+
+This allows you access to the related objects from the template without altering any views. For example, if you only had ``Entry`` models related to :py:class:`Category`, your ``categories/category_detail.html`` template could look like
+
+.. literalinclude:: usage_example_template.html
+   :language: django
+   :linenos:
+
+
+If you have ``related_name`` parameters to the configuration (see :ref:`registering_models`), then you would use ``category.related_name.all`` instead of ``category.relatedmodel_set.all``\ .
+
+
+Template Tags
+=============
+
+To use the template tags::
 
 	{% import category_tags %}
 
-Filters
-*******
 
 ``tree_info``
 -------------
@@ -41,4 +58,5 @@ comma-separated list of feature names. The valid feature names are:
 
          Books                    ->  []
             Sci-fi                ->  [u'Books']
-               Dystopian Futures  ->  [u'Books', u'Sci-fi']
+               Dystopian Futures  ->  [u'Books', u'Sci-fi']
+
diff --git a/docs/adding_the_fields.html b/docs/adding_the_fields.html
@@ -6,13 +6,13 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Adding the fields to the database &mdash; Django Categories v0.8 documentation</title>
+    <title>Adding the fields to the database &mdash; Django Categories v0.8.2 documentation</title>
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.8',
+        VERSION:     '0.8.2',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -21,13 +21,13 @@
     <script type="text/javascript" src="_static/jquery.js"></script>
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
-    <link rel="top" title="Django Categories v0.8 documentation" href="index.html" />
+    <link rel="top" title="Django Categories v0.8.2 documentation" href="index.html" />
     <link rel="next" title="Reference" href="reference/index.html" />
     <link rel="prev" title="Registering Models" href="registering_models.html" /> 
   </head>
   <body>
 <div id="docstitle">
-	<p>Django Categories v0.8 documentation</p>
+	<p>Django Categories v0.8.2 documentation</p>
 </div>
 <div id="header">
 	<div id="title"><h1>Adding the fields to the database</h1></div>

diff --git a/docs/genindex.html b/docs/genindex.html
@@ -6,13 +6,13 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Index &mdash; Django Categories v0.8 documentation</title>
+    <title>Index &mdash; Django Categories v0.8.2 documentation</title>
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.8',
+        VERSION:     '0.8.2',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -21,11 +21,11 @@
     <script type="text/javascript" src="_static/jquery.js"></script>
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
-    <link rel="top" title="Django Categories v0.8 documentation" href="index.html" /> 
+    <link rel="top" title="Django Categories v0.8.2 documentation" href="index.html" /> 
   </head>
   <body>
 <div id="docstitle">
-	<p>Django Categories v0.8 documentation</p>
+	<p>Django Categories v0.8.2 documentation</p>
 </div>
 <div id="header">
 	<div id="title"><h1>Index</h1></div>

diff --git a/docs/getting_started.html b/docs/getting_started.html
@@ -6,13 +6,13 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Getting Started &mdash; Django Categories v0.8 documentation</title>
+    <title>Getting Started &mdash; Django Categories v0.8.2 documentation</title>
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.8',
+        VERSION:     '0.8.2',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -21,13 +21,13 @@
     <script type="text/javascript" src="_static/jquery.js"></script>
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
-    <link rel="top" title="Django Categories v0.8 documentation" href="index.html" />
+    <link rel="top" title="Django Categories v0.8.2 documentation" href="index.html" />
     <link rel="next" title="Using categories in templates" href="usage.html" />
-    <link rel="prev" title="Django Categories v 0.8" href="index.html" /> 
+    <link rel="prev" title="Django Categories v 0.8.2" href="index.html" /> 
   </head>
   <body>
 <div id="docstitle">
-	<p>Django Categories v0.8 documentation</p>
+	<p>Django Categories v0.8.2 documentation</p>
 </div>
 <div id="header">
 	<div id="title"><h1>Getting Started</h1></div>
@@ -36,7 +36,7 @@
 		<li id="page_buttons">
 			<div class="headerButton"><a href="genindex.html" title="General Index" accesskey="I">index</a></div>
 			<div class="headerButton"><a href="usage.html" title="Using categories in templates" accesskey="N">next</a></div>
-			<div class="headerButton"><a href="index.html" title="Django Categories v 0.8" accesskey="P">previous</a></div>
+			<div class="headerButton"><a href="index.html" title="Django Categories v 0.8.2" accesskey="P">previous</a></div>
 		</li>
 	</ul>
 </div>

diff --git a/docs/index.html b/docs/index.html
@@ -6,13 +6,13 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Django Categories v 0.8 &mdash; Django Categories v0.8 documentation</title>
+    <title>Django Categories v 0.8.2 &mdash; Django Categories v0.8.2 documentation</title>
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.8',
+        VERSION:     '0.8.2',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -21,15 +21,15 @@
     <script type="text/javascript" src="_static/jquery.js"></script>
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
-    <link rel="top" title="Django Categories v0.8 documentation" href="#" />
+    <link rel="top" title="Django Categories v0.8.2 documentation" href="#" />
     <link rel="next" title="Getting Started" href="getting_started.html" /> 
   </head>
   <body>
 <div id="docstitle">
-	<p>Django Categories v0.8 documentation</p>
+	<p>Django Categories v0.8.2 documentation</p>
 </div>
 <div id="header">
-	<div id="title"><h1>Django Categories v 0.8</h1></div>
+	<div id="title"><h1>Django Categories v 0.8.2</h1></div>
 	<ul id="headerButtons">
 		<li id="toc_button"><div class="headerButton"><a href="#">Table of Contents</a></div></li>
 		<li id="page_buttons">
@@ -83,7 +83,7 @@ <h3>This Page</h3>
           <div class="body">
 
   <div class="section" id="django-categories-v-version">
-<h1>Django Categories v 0.8<a class="headerlink" href="#django-categories-v-version" title="Permalink to this headline">¶</a></h1>
+<h1>Django Categories v 0.8.2<a class="headerlink" href="#django-categories-v-version" title="Permalink to this headline">¶</a></h1>
 <p>Contents:</p>
 <div class="toctree-wrapper compound">
 <ul>
@@ -92,7 +92,8 @@ <h1>Django Categories v 0.8<a class="headerlink" href="#django-categories-v-vers
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="usage.html">Using categories in templates</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="usage.html#filters">Filters</a></li>
+<li class="toctree-l2"><a class="reference internal" href="usage.html#getting-all-items-within-a-category">Getting all items within a category</a></li>
+<li class="toctree-l2"><a class="reference internal" href="usage.html#template-tags">Template Tags</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="registering_models.html">Registering Models</a><ul>
@@ -138,7 +139,7 @@ <h2>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Pe
       <div class="clearer"></div>
     </div>
 	<div id="breadcrumbs">
-		Django Categories v 0.8
+		Django Categories v 0.8.2
 		</ul>
 	</div>
 	<script type="text/javascript" charset="utf-8" src="_static/toc.js"></script>

diff --git a/docs/objects.inv b/docs/objects.inv
diff --git a/docs/reference/index.html b/docs/reference/index.html
@@ -6,13 +6,13 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Reference &mdash; Django Categories v0.8 documentation</title>
+    <title>Reference &mdash; Django Categories v0.8.2 documentation</title>
     <link rel="stylesheet" href="../_static/default.css" type="text/css" />
     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '../',
-        VERSION:     '0.8',
+        VERSION:     '0.8.2',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -21,13 +21,13 @@
     <script type="text/javascript" src="../_static/jquery.js"></script>
     <script type="text/javascript" src="../_static/underscore.js"></script>
     <script type="text/javascript" src="../_static/doctools.js"></script>
-    <link rel="top" title="Django Categories v0.8 documentation" href="../index.html" />
+    <link rel="top" title="Django Categories v0.8.2 documentation" href="../index.html" />
     <link rel="next" title="Management Commands" href="management_commands.html" />
     <link rel="prev" title="Adding the fields to the database" href="../adding_the_fields.html" /> 
   </head>
   <body>
 <div id="docstitle">
-	<p>Django Categories v0.8 documentation</p>
+	<p>Django Categories v0.8.2 documentation</p>
 </div>
 <div id="header">
 	<div id="title"><h1>Reference</h1></div>

diff --git a/docs/reference/management_commands.html b/docs/reference/management_commands.html
@@ -6,13 +6,13 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Management Commands &mdash; Django Categories v0.8 documentation</title>
+    <title>Management Commands &mdash; Django Categories v0.8.2 documentation</title>
     <link rel="stylesheet" href="../_static/default.css" type="text/css" />
     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '../',
-        VERSION:     '0.8',
+        VERSION:     '0.8.2',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -21,14 +21,14 @@
     <script type="text/javascript" src="../_static/jquery.js"></script>
     <script type="text/javascript" src="../_static/underscore.js"></script>
     <script type="text/javascript" src="../_static/doctools.js"></script>
-    <link rel="top" title="Django Categories v0.8 documentation" href="../index.html" />
+    <link rel="top" title="Django Categories v0.8.2 documentation" href="../index.html" />
     <link rel="up" title="Reference" href="index.html" />
     <link rel="next" title="Models" href="models.html" />
     <link rel="prev" title="Reference" href="index.html" /> 
   </head>
   <body>
 <div id="docstitle">
-	<p>Django Categories v0.8 documentation</p>
+	<p>Django Categories v0.8.2 documentation</p>
 </div>
 <div id="header">
 	<div id="title"><h1>Management Commands</h1></div>

diff --git a/docs/reference/models.html b/docs/reference/models.html
@@ -6,13 +6,13 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Models &mdash; Django Categories v0.8 documentation</title>
+    <title>Models &mdash; Django Categories v0.8.2 documentation</title>
     <link rel="stylesheet" href="../_static/default.css" type="text/css" />
     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '../',
-        VERSION:     '0.8',
+        VERSION:     '0.8.2',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -21,14 +21,14 @@
     <script type="text/javascript" src="../_static/jquery.js"></script>
     <script type="text/javascript" src="../_static/underscore.js"></script>
     <script type="text/javascript" src="../_static/doctools.js"></script>
-    <link rel="top" title="Django Categories v0.8 documentation" href="../index.html" />
+    <link rel="top" title="Django Categories v0.8.2 documentation" href="../index.html" />
     <link rel="up" title="Reference" href="index.html" />
     <link rel="next" title="Settings" href="settings.html" />
     <link rel="prev" title="Management Commands" href="management_commands.html" /> 
   </head>
   <body>
 <div id="docstitle">
-	<p>Django Categories v0.8 documentation</p>
+	<p>Django Categories v0.8.2 documentation</p>
 </div>
 <div id="header">
 	<div id="title"><h1>Models</h1></div>