* Fixed bug in conf.py, where it was trying to use the old VERSION variable in django...

* Updated the documentation to clarify the use-cases for column formatters.

diff --git a/docs/conf.py b/docs/conf.py
index 9fcd66ff7f140388a25007acb3c8aeb04b38151e..2ebada62b35975a6686da5bfabc7d14cab3851bf 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -50,9 +50,9 @@ project = u'django-tables'
 # built documents.
 #
 # The short X.Y version.
-version = '.'.join(map(str, tables.VERSION[0:2]))
+version = '0.4.0.alpha2.dev'
 # The full version, including alpha/beta/rc tags.
-release = tables.get_version()
+release = '0.4.0.alpha2.dev'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/index.rst b/docs/index.rst
index e79be2135951714447279e6e85e54dacff22763e..03d3b1f6b6c1c914c2bf5d2213fe0e00da4102f7 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -142,9 +142,12 @@ control you want, the less easy it is to use).
 Column formatter
 ----------------
 
-If all you want to do is change the way a column is formatted, you can simply
-provide the :attr:`~Column.formatter` argument to a :class:`Column` when you
-define the :class:`Table`:
+Using a formatter is a quick way to adjust the way values are displayed in a
+column. A limitation of this approach is that you *only* have access to a
+single attribute of the data source.
+
+To use a formatter, simply provide the :attr:`~Column.formatter` argument to a
+:class:`Column` when you define the :class:`Table`:
 
 .. code-block:: python
 
@@ -161,10 +164,17 @@ define the :class:`Table`:
     #10
     31 years old
 
-The limitation of this approach is that you're unable to incorporate any
-run-time information of the table into the formatter. For example it would not
-be possible to incorporate the row number into the cell's value.
+As you can see, the only the value of the column is available to the formatter.
+This means that **it's impossible create a formatter that incorporates other
+values of the record**, e.g. a column with an ``<a href="...">`` that uses
+:func:`reverse` with the record's ``pk``.
+
+If formatters aren't powerful enough, you'll need to either :ref:`create a
+Column subclass <subclassing-column>`, or to use the
+:ref:`Table.render_FOO method <table.render_foo>`.
+
 
+.. _table.render_foo:
 
 :meth:`Table.render_FOO` Method
 -------------------------------
@@ -177,8 +187,10 @@ DRY).
 The example below has a number of different techniques in use:
 
 * :meth:`Column.render` (accessible via :attr:`BoundColumn.column`) applies the
-  *formatter* function if it's been provided. This is evident in the order that
-  the square and angled brackets have been applied for the ``id`` column.
+  *formatter* if it's been provided. The effect of this behaviour can be seen
+  below in the output for the ``id`` column. Square brackets (from the
+  *formatter*) have been applied *after* the angled brackets (from the
+  :meth:`~Table.render_FOO`).
 * Completely abitrary values can be returned by :meth:`render_FOO` methods, as
   shown in :meth:`~SimpleTable.render_row_number` (a :attr:`_counter` attribute
   is added to the :class:`SimpleTable` object to keep track of the row number).
@@ -213,6 +225,11 @@ The example below has a number of different techniques in use:
     <[10]>
     31 years old
 
+The :meth:`Column.render` method is what actually performs the lookup into a
+record to retrieve the column value. In the example above, the
+:meth:`render_row_number` never called :meth:`Column.render` and as a result
+there was not attempt to access the data source to retrieve a value.
+
 
 Custom Template
 ---------------
@@ -244,6 +261,8 @@ ignore the built-in generation tools, and instead pass an instance of your
     </table>
 
 
+.. _subclassing-column:
+
 Subclassing :class:`Column`
 ---------------------------