Added Python 3 compatibility notes.

docs/index.rst

@@ -44,6 +44,7 @@ you up and running:
    debugging
 
    migration_from_1_to_2
+   python3
    contributing
 
 

docs/python3.rst

@@ -0,0 +1,59 @@
+.. _ref-python3:
+
+================
+Python 3 Support
+================
+
+As of Haystack v2.1.0, it has been ported to support both Python 2 & Python 3
+within the same codebase. This builds on top of what `six`_ & `Django`_ provide.
+
+No changes are required for anyone running an existing Haystack
+installation. The API is completely backward-compatible, so you should be able
+to run your existing software without modification.
+
+Virtually all tests pass under both Python 2 & 3, with a small number of
+expected failures under Python (typically related to ordering, see below).
+
+.. _`six`: http://pythonhosted.org/six/
+.. _`Django`: https://docs.djangoproject.com/en/1.5/topics/python3/#str-and-unicode-methods
+
+
+Supported Backends
+==================
+
+The following backends are fully supported under Python 3. However, you may
+need to update these dependencies if you have a pre-existing setup.
+
+* Solr (pysolr>=3.1.0)
+* Elasticsearch (pyelasticsearch>=0.5)
+
+
+Partially Supported Backends
+============================
+
+Most aspects of Whoosh work fine under Python 3. However, the built-in
+highlighting fails under Python 3.3.2. Using the Haystack-provided template tag
+highlighting is a good stopgap until
+https://bitbucket.org/mchaput/whoosh/324/highlighting-under-python-3-fails is
+resolved.
+
+* Whoosh (whoosh>=2.5.0)
+
+
+Notes
+=====
+
+Testing
+-------
+
+If you were testing things such as the query generated by a given
+``SearchQuerySet`` or how your forms would render, under Python 3.3.2+,
+`hash randomization`_ is in effect, which means that the ordering of
+dictionaries is no longer consistent, even on the same platform.
+
+Haystack took the approach of abandoning making assertions about the entire
+structure. Instead, we either simply assert that the new object contains the
+right things or make a call to ``sorted(...)`` around it to ensure order. It is
+recommended you take a similar approach.
+
+.. _`hash randomization`: http://docs.python.org/3/whatsnew/3.3.html#builtin-functions-and-types

docs/toc.rst

@@ -20,6 +20,7 @@ Table Of Contents
    debugging
 
    migration_from_1_to_2
+   python3
    contributing
 
    best_practices