Update setup_description.rst using `setup.py prep`.

1 files changed, 70 insertions, 15 deletions

diff --git a/setup_description.rst b/setup_description.rst
index 4e97663..d415249 100644
--- a/setup_description.rst
+++ b/setup_description.rst
@@ -1,18 +1,29 @@
-.. This file is auto-generated by setup.py for PyPI using pandoc, so this
-.. file should not be edited.  Edits should go in the source files.
+.. Do not edit this file.  This file is auto-generated for PyPI by setup.py
+.. using pandoc, so edits should go in the source files rather than here.
 
 Pystache
 ========
 
 .. raw:: html
 
-   <!-- We leave the brackets empty.  Otherwise, text shows up in the reST
-     version converted by pandoc. -->
+   <!-- Since PyPI rejects reST long descriptions that contain HTML, -->
+   <!-- HTML comments must be removed when converting this file to reST. -->
+   <!-- For more information on PyPI's behavior in this regard, see: -->
+   <!-- http://docs.python.org/distutils/uploading.html#pypi-package-display -->
+   <!-- The Pystache setup script strips 1-line HTML comments prior -->
+   <!-- to converting to reST, so all HTML comments should be one line. -->
+
+   <!-- We leave the leading brackets empty here.  Otherwise, unwanted -->
+   <!-- caption text shows up in the reST version converted by pandoc. -->
 
 .. figure:: https://s3.amazonaws.com/webdev_bucket/pystache.png
    :align: center
    :alt: mustachioed, monocled snake by David Phillips
 
+.. figure:: https://secure.travis-ci.org/defunkt/pystache.png?branch=master,development
+   :align: center
+   :alt: 
+
 `Pystache <https://github.com/defunkt/pystache>`_ is a Python
 implementation of `Mustache <http://mustache.github.com/>`_. Mustache is
 a framework-agnostic, logic-free templating system inspired by
@@ -46,6 +57,14 @@ Pystache is tested with--
 -  Python 2.7
 -  Python 3.1
 -  Python 3.2
+-  `PyPy <http://pypy.org/>`_
+
+`Distribute <http://packages.python.org/distribute/>`_ (the setuptools
+fork) is recommended over
+`setuptools <http://pypi.python.org/pypi/setuptools>`_, and is required
+in some cases (e.g. for Python 3 support). If you use
+`pip <http://www.pip-installer.org/>`_, you probably already satisfy
+this requirement.
 
 JSON support is needed only for the command-line interface and to run
 the spec tests. We require simplejson for earlier versions of Python
@@ -67,6 +86,11 @@ Install It
 ::
 
     pip install pystache
+
+And test it--
+
+::
+
     pystache-test
 
 To install and test from source (e.g. from GitHub), see the Develop
@@ -147,8 +171,8 @@ Pystache has supported Python 3 since version 0.5.1. Pystache behaves
 slightly differently between Python 2 and 3, as follows:
 
 -  In Python 2, the default html-escape function ``cgi.escape()`` does
-   not escape single quotes; whereas in Python 3, the default escape
-   function ``html.escape()`` does escape single quotes.
+   not escape single quotes. In Python 3, the default escape function
+   ``html.escape()`` does escape single quotes.
 -  In both Python 2 and 3, the string and file encodings default to
    ``sys.getdefaultencoding()``. However, this function can return
    different values under Python 2 and 3, even when run from the same
@@ -207,7 +231,8 @@ command!), you can use `tox <http://pypi.python.org/pypi/tox>`_:
 
 ::
 
-    pip install tox
+    pip install 'virtualenv<1.8'  # Version 1.8 dropped support for Python 2.4.
+    pip install 'tox<1.4'  # Version 1.4 dropped support for Python 2.4.
     tox
 
 If you do not have all Python versions listed in ``tox.ini``--
@@ -241,18 +266,42 @@ To run a subset of the tests, you can use
     pip install nose
     nosetests --tests pystache/tests/test_context.py:GetValueTests.test_dictionary__key_present
 
-**Running Pystache from source with Python 3.** Pystache is written in
-Python 2 and must be converted with
-`2to3 <http://docs.python.org/library/2to3.html>`_ prior to running
-under Python 3. The installation process (and tox) do this conversion
+Using Python 3 with Pystache from source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pystache is written in Python 2 and must be converted to Python 3 prior
+to using it with Python 3. The installation process (and tox) do this
 automatically.
 
+To convert the code to Python 3 manually (while using Python 3)--
+
+::
+
+    python setup.py build
+
+This writes the converted code to a subdirectory called ``build``. By
+design, Python 3 builds
+`cannot <https://bitbucket.org/tarek/distribute/issue/292/allow-use_2to3-with-python-2>`_
+be created from Python 2.
+
+To convert the code without using setup.py, you can use
+`2to3 <http://docs.python.org/library/2to3.html>`_ as follows (two
+steps)--
+
+::
+
+    2to3 --write --nobackups --no-diffs --doctests_only pystache
+    2to3 --write --nobackups --no-diffs pystache
+
+This converts the code (and doctests) in place.
+
 To ``import pystache`` from a source distribution while using Python 3,
 be sure that you are importing from a directory containing a converted
-version (e.g. from your site-packages directory after manually
-installing) and not from the original source directory. Otherwise, you
-will get a syntax error. You can help ensure this by not running the
-Python IDE from the project directory when importing Pystache.
+version of the code (e.g. from the ``build`` directory after
+converting), and not from the original (unconverted) source directory.
+Otherwise, you will get a syntax error. You can help prevent this by not
+running the Python IDE from the project directory when importing
+Pystache while using Python 3.
 
 Mailing List
 ------------
@@ -280,13 +329,19 @@ History
 
 -  Added option of raising errors on missing tags/partials:
    ``Renderer(missing_tags='strict')`` (issue #110).
+-  Added support for finding and loading templates by file name in
+   addition to by template name (issue #127). [xgecko]
 -  Added a ``parse()`` function that yields a printable, pre-compiled
    parse tree.
 -  Added support for rendering pre-compiled templates.
+-  Added support for `PyPy <http://pypy.org/>`_ (issue #125).
+-  Added support for `Travis CI <http://travis-ci.org>`_ (issue #124).
+   [msabramo]
 -  Bugfix: exceptions raised from a property are no longer swallowed
    when getting a key from a context stack (issue #110).
 -  Bugfix: lambda section values can now return non-ascii, non-unicode
    strings (issue #118).
+-  Convert HISTORY and README files from reST to Markdown.
 -  More robust handling of byte strings in Python 3.
 
 0.5.2 (2012-05-03)