Permalink
Browse files

Documentation updates.

  • Loading branch information...
1 parent acd300c commit 6a1437f2b844541c032200005688ce2043db85b1 Malcolm Tredinnick committed May 17, 2009
Showing with 104 additions and 16 deletions.
  1. BIN docs/_static/basic-admin.png
  2. +33 −14 docs/basic-usage.rst
  3. +9 −2 docs/index.rst
  4. +62 −0 docs/introduction.rst
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
@@ -10,11 +10,13 @@ another model. You create a ``ForeignKey`` or ``ManyToManyField`` link between
your model and ``acacia.models.Topic`` and use it to store the category (or
categories, in the latter case).
-For example, to categorise a series of articles, you might have the following
-model::
+For example, to categorise a series of articles, you might create the following
+model:
+
+.. parsed-literal::
from django.db import models
- from acacia import models as acacia_models
+ **from acacia import models as acacia_models**
class Author(models.Model):
...
@@ -23,29 +25,43 @@ model::
title = models.CharField(max_length=150)
author = models.ForeignKey(Author)
text = models.FileField(upload_to="%Y%m%d")
- topics = models.ManyToManyField(acacia_models.Topic)
+ **topics = models.ManyToManyField(acacia_models.Topic)**
+
+That's all that is needed, aside from adding ``acacia`` to the
+``INSTALLED_APPS`` tuple in your Django settings file. You can create topics
+and assign them to the ``Article`` model in the admin interface or directly in
+Python code. These two approaches are covered in the following sections.
+
+.. admonition:: Docs TODO
-Working With Topics Via The Admin Interface
+ Eventually, I'll write about customised Topic subclasses so that things
+ like topics associated only with a particular model can be implemented.
+
+Working With Topics In The Admin Interface
===========================================
Although the internals of the ``Topic`` model are fairly complex, the admin
-interface is very straightforward. You can edit the name of a node in the tree
-and the parent of the node.
+interface is very straightforward. For any node in the tree, you can edit its
+name and parent.
+
+.. image:: _static/basic-admin.png
+ :alt: Default admin change page for the Topic model.
The *name* of an individual node is the final component of the full name. Thus,
-if the node's full name (path) is ``"timeframe/today/urgent"``, the name of the
-node is ``"urgent"``. The parent of that node is the ``"timeframe/today"`` node.
+if the node's full name is "timeframe/today/urgent", the name of the node is
+"urgent". The parent of that node is the "timeframe/today" node.
Topic nodes are sorted lexicographically by their full name when presented in
-the admin. Given the nodes, ``"pet"``, ``"pet/dog"``, ``"pet/cat"`` and
-``"owners"``, they will sort in this order::
+the admin. Given the nodes, "pet", "pet/dog", "pet/cat" and "owners", they will
+sort in this order::
owners
pet
pet/cat
pet/dog
-This makes finding the appropriate node in a list fairly straightforward.
+This makes finding the appropriate node in a list fairly straightforward, since
+all children are grouped together, immediately after their parent.
.. admonition:: Coming Soon
@@ -54,11 +70,14 @@ This makes finding the appropriate node in a list fairly straightforward.
even a few dozen topics, the selection list can become quite long and
unwieldy.
-Selecting Topics Objects In Django Code
-=======================================
+Working With Topics In Django Code
+==================================
.. currentmodule:: acacia.models
+Selecting Topics
+----------------
+
It will be common ``Acacia`` usage to want to select :class:`Topic` objects
using their full, human-readable names. Those names are natural candidates for
using in URLs and the like, so you need to be able to return from the string
View
@@ -2,14 +2,21 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to Acacia's documentation!
-==================================
+Documentation For Acacia
+========================
+
+Acacia is a small Django application that provides hierarchical topic or
+category objects. Other Django applications can then use the topic trees to
+categorise objects using human-readable names. The primary use of this
+application is to provide a tree structure with a way to retrieve nodes in the
+hierarchy using the human-readable name of the node.
Contents:
.. toctree::
:maxdepth: 2
+ introduction
basic-usage
Indices and tables
View
@@ -0,0 +1,62 @@
+============
+Introduction
+============
+
+Topic Trees Versus Tagging
+===========================
+
+These days, it seems that *"tagging"* is the trendy thing to provide on sites
+with large amounts of contents. Tags, individual labels attached to items of
+content, provide a *flat* structure for categorisation. In a wide number of
+situations, experience has shown that this is all the complexity that is
+needed. It's possible to provide easy searchability and qualification using
+only a single layer of labels.
+
+In more complex situations, introducing extra structure into the labels,
+by grouping them into hierarchies, is very useful. Using a common name for
+labels structured in a hierarchy is a bit harder, since they aren't as common
+as tag-based systems. Throughout this documentation, we'll use *categories* or
+*topic trees* as a descriptive name for these types of labellings.
+
+It's obviously possible to fake hierarchies by using a flat tagging system,
+simply by encoding the full name of each node in the tree into the tag name.
+You could, for example, use "software/debugging" as a tag name. Although
+this works, in a fashion, operating as others do has a lot of benefits in the
+web space and tagging systems do not typically use separators in tag names like
+this. Your tags won't look like other people's tags if you adopt this approach
+(and call your labels *tags*).
+
+There's also a question of usability on the content creator's side of the
+operation. A true hierarchy allows you to move entire subtrees at once. If you
+have a whole group of topics under "software/python/", you might want to move
+all those Python-related tags to live under "software/languages/python/"
+instead. A normal tagging system won't understand that there's a relationship
+between labels in this situation and won't relabel all the appropriate nodes
+when the "python" node is moved to a new parent.
+
+In short, tagging is not a bad labelling system. Website experiences over the
+last decade has shown that. However, if you need a more structured system, it's
+worth using a proper tree-like modelling scheme, rather than trying to fake the
+names with tags.
+
+Topic Trees Are Trees Plus Some Extras
+=======================================
+
+If you are in a situation where an hierarchical labelling system is
+appropriate, it might seem that you are somewhat be spoilt for choice. There
+are a number of tree implementations available for reuse in Django projects. At
+the time of writing, probably the two most well-known examples are django-mptt_
+and django-treebeard_. Both of these packages provide some well thought out
+implementations of tree structures for Django models.
+
+.. _django-mptt: http://code.google.com/p/django-mptt/
+.. _django-treebeard: http://code.google.com/p/django-treebeard/
+
+For topic trees, however, some extra work still remains to be done after you
+have set up your models in an appropriate fashion. This is because you will
+typically be trying to look up the topics or categories using a human-readable
+name. Internally, though, the nodes in the tree won't be stored or related in
+that fashion. Acacia has been developed to provide an extra layer of wrapper
+functions and make those common lookup patterns (and similar manipulations)
+easy.
+

0 comments on commit 6a1437f

Please sign in to comment.