Permalink
Browse files

A bunch more documentation updates and cleanups.

  • Loading branch information...
1 parent 6a1437f commit 36a03151dcf18d4a0f1d5b9ef67b952078d946d8 Malcolm Tredinnick committed May 17, 2009
View
@@ -4,33 +4,7 @@ Acacia -- Simple Topic Trees
Acacia is a small Django application that provides hierarchical topic or
category naming. Other Django applications can then use the topic trees to
-categorise articles or objects with human-readable names. For example::
-
- root_1
- root_1/child_1
- root_1/child_2
- root_2
- root_2/child_1
- root_2/child_1/grandchild_1
- root_2/child_2
-
-Each model instance in this application is one node in the hierarchy, defining
-only the name for that node (which is the parent's name plus the node's
-individual name). Further information could be added to the nodes through
-subclassing.
-
-Individual node names can be reused in multiple places in the tree, which is
-where this system provides an advantage over tagging. It allows you to create
-"debugging" nodes under both "software/" and "hardware/" and have them remain
-distinct.
-
-Admin Support
-=============
-
-The topic tree can be edited directly in the admin interface. Admin users can
-create new node names and reparent existing nodes directly.
-
-(Coming soon: nifty Javascript manipulation)
+categorise articles or objects with human-readable names.
Dependencies
============
@@ -47,12 +21,6 @@ the Python import path, not part of Django's ``INSTALLED_APPS`` setting).
More Documentation
==================
-Further documentation, containing information about usage, extending the
-nodes, using the hierarchy with multiple models, and providing easy use with
-other applications in the admin application is coming soon. The current code
-is an initial dump of what I've been working with.
-
-Eager early adopters can probably work out most of the extensions themselves
-in any case, using intermediate many-to-many tables and model inheritance in
-appropriate places to provide extensions.
+Full documentation for Acacia is available in the docs/ directory of the
+source.
View
@@ -0,0 +1,24 @@
+==============
+Advanced Usage
+==============
+
+None of the topics in this section are particularly advanced in terms of the
+coding skill required. They are all slight extensions to the default topic tree
+or Django behaviour, and so require familiarity with how Acacia works without
+any customisation.
+
+Javascript Admin Widget
+=======================
+
+*(Coming soon)*
+
+Javascript Form Widget
+======================
+
+*(Coming soon)*
+
+.. _advanced-custom-nodes:
+
+Customising Topic Nodes
+=======================
+
File renamed without changes
View
@@ -1,10 +1,10 @@
-==================
-Simple Topic Trees
-==================
-
+===========
Basic Usage
===========
+Adding Topic Classification To A Model
+======================================
+
The most direct usage of Acacia's topic trees is to categorise entries in
another model. You create a ``ForeignKey`` or ``ManyToManyField`` link between
your model and ``acacia.models.Topic`` and use it to store the category (or
@@ -27,15 +27,17 @@ model:
text = models.FileField(upload_to="%Y%m%d")
**topics = models.ManyToManyField(acacia_models.Topic)**
-That's all that is needed, aside from adding ``acacia`` to the
+That is 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
-
- Eventually, I'll write about customised Topic subclasses so that things
- like topics associated only with a particular model can be implemented.
+In this standard usage, every topic in the topic tree is available for use by
+every model that links to the ``acacia.models.Topic`` model. This means you can
+use the same categorisation across multiple models. If you want to have
+different topics for different models or control the topics that are available
+to a model in some other way, refer to the :ref:`advanced-custom-nodes`
+section, elsewhere in this documentation.
Working With Topics In The Admin Interface
===========================================
@@ -44,7 +46,7 @@ Although the internals of the ``Topic`` model are fairly complex, the admin
interface is very straightforward. For any node in the tree, you can edit its
name and parent.
-.. image:: _static/basic-admin.png
+.. image:: 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,
View
@@ -0,0 +1,9 @@
+====================
+Implementation Notes
+====================
+
+Full Name Length Limit
+======================
+
+*TODO: Document the upper bound on full name lengths.*
+
View
@@ -18,6 +18,8 @@ Contents:
introduction
basic-usage
+ advanced-usage
+ implementation
Indices and tables
==================
View
@@ -9,35 +9,35 @@ 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
+needed. It is 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
+labels structured in a hierarchy is a bit harder, since they are not 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,
+It is 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*).
+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 will not 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
+There is 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.
+instead. A normal tagging system does not understand that there is a
+relationship between labels in this situation and would not 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.
+last decade has shown that. However, if you need a more structured system, it
+is worth using a proper tree-like modelling scheme, rather than trying to fake
+the names with tags.
Topic Trees Are Trees Plus Some Extras
=======================================
@@ -53,10 +53,30 @@ implementations of tree structures for Django models.
.. _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.
+have set up your models in an appropriate fashion for working with them as
+trees. This is because you will typically be trying to look up and create the
+topics or categories using a human-readable name. Internally, the nodes in the
+tree are not stored or related in that fashion, so some conversion functions
+are always necessary.
+
+What Acacia Provides
+---------------------
+
+Acacia has been developed to provide an extra layer of wrapper functions in
+order to make those common lookup patterns (and similar manipulations) easy. It
+is uses django-treebeard_ for the tree implementation and provides a few
+convenience functions for
+
+ * Looking up a node using the full name (e.g. "software/languages/python").
+ * Retrieving all the nodes under the node with a particular full name (e.g.
+ all the nodes in the "software/languages/" part of the hierarchy).
+ * Creating a node, with all the necessary parents, with a particular full
+ name.
+
+Acacia also comes with a nice, customised admin interface for working with
+topic trees. The implementation of a node in a topic tree is fairly complex,
+but most of the complexities is machinery that helps make lookups and other
+tree operations very fast. They are not details that are used by a developer or
+administrator using the tree in normal operations and the admin interface for
+Acacia's models hides the implementation details.

0 comments on commit 36a0315

Please sign in to comment.