Completed `python setup.py prep` command to generate .rst from .md.

7 files changed, 280 insertions, 170 deletions

diff --git a/.gitignore b/.gitignore
index c9b5217..9761831 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,8 @@
 # Our tox runs convert the doctests in *.rst files to Python 3 prior to
 # running tests.  Ignore these temporary files.
 *.temp2to3.rst
+# The setup.py "prep" command converts *.md to *.temp.rst.
+*.temp.rst
 # TextMate project file
 *.tmproj
 # Distribution-related folders and files.
diff --git a/README.rst b/DESCRIPTION.rst
index e657572..934ecb9 100644
--- a/README.rst
+++ b/DESCRIPTION.rst
@@ -1,3 +1,5 @@
+.. This file is auto-generated by setup.py, so it should not be edited.
+
 Pystache
 ========
 
@@ -264,3 +266,176 @@ Authors
     Author: Chris Wanstrath
     Maintainer: Chris Jerdonek
 
+
+History
+=======
+
+0.5.3 (TBD)
+-----------
+
+-  Added option of raising errors on missing tags/partials:
+   ``Renderer(missing_tags='strict')`` (issue #110).
+-  Added a ``parse()`` function that yields a printable, pre-compiled
+   parse tree.
+-  Added support for rendering pre-compiled templates.
+-  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).
+-  More robust handling of byte strings in Python 3.
+
+0.5.2 (2012-05-03)
+------------------
+
+-  Added support for dot notation and version 1.1.2 of the spec (issue
+   #99). [rbp]
+-  Missing partials now render as empty string per latest version of
+   spec (issue #115).
+-  Bugfix: falsey values now coerced to strings using str().
+-  Bugfix: lambda return values for sections no longer pushed onto
+   context stack (issue #113).
+-  Bugfix: lists of lambdas for sections were not rendered (issue #114).
+
+0.5.1 (2012-04-24)
+------------------
+
+-  Added support for Python 3.1 and 3.2.
+-  Added tox support to test multiple Python versions.
+-  Added test script entry point: pystache-test.
+-  Added \_\_version\_\_ package attribute.
+-  Test harness now supports both YAML and JSON forms of Mustache spec.
+-  Test harness no longer requires nose.
+
+0.5.0 (2012-04-03)
+------------------
+
+This version represents a major rewrite and refactoring of the code base
+that also adds features and fixes many bugs. All functionality and
+nearly all unit tests have been preserved. However, some backwards
+incompatible changes to the API have been made.
+
+Below is a selection of some of the changes (not exhaustive).
+
+Highlights:
+
+-  Pystache now passes all tests in version 1.0.3 of the `Mustache
+   spec <https://github.com/mustache/spec>`_. [pvande]
+-  Removed View class: it is no longer necessary to subclass from View
+   or from any other class to create a view.
+-  Replaced Template with Renderer class: template rendering behavior
+   can be modified via the Renderer constructor or by setting attributes
+   on a Renderer instance.
+-  Added TemplateSpec class: template rendering can be specified on a
+   per-view basis by subclassing from TemplateSpec.
+-  Introduced separation of concerns and removed circular dependencies
+   (e.g. between Template and View classes, cf. `issue
+   #13 <https://github.com/defunkt/pystache/issues/13>`_).
+-  Unicode now used consistently throughout the rendering process.
+-  Expanded test coverage: nosetests now runs doctests and ~105 test
+   cases from the Mustache spec (increasing the number of tests from 56
+   to ~315).
+-  Added a rudimentary benchmarking script to gauge performance while
+   refactoring.
+-  Extensive documentation added (e.g. docstrings).
+
+Other changes:
+
+-  Added a command-line interface. [vrde]
+-  The main rendering class now accepts a custom partial loader (e.g. a
+   dictionary) and a custom escape function.
+-  Non-ascii characters in str strings are now supported while
+   rendering.
+-  Added string encoding, file encoding, and errors options for decoding
+   to unicode.
+-  Removed the output encoding option.
+-  Removed the use of markupsafe.
+
+Bug fixes:
+
+-  Context values no longer processed as template strings.
+   [jakearchibald]
+-  Whitespace surrounding sections is no longer altered, per the spec.
+   [heliodor]
+-  Zeroes now render correctly when using PyPy. [alex]
+-  Multline comments now permitted. [fczuardi]
+-  Extensionless template files are now supported.
+-  Passing ``**kwargs`` to ``Template()`` no longer modifies the
+   context.
+-  Passing ``**kwargs`` to ``Template()`` with no context no longer
+   raises an exception.
+
+0.4.1 (2012-03-25)
+------------------
+
+-  Added support for Python 2.4. [wangtz, jvantuyl]
+
+0.4.0 (2011-01-12)
+------------------
+
+-  Add support for nested contexts (within template and view)
+-  Add support for inverted lists
+-  Decoupled template loading
+
+0.3.1 (2010-05-07)
+------------------
+
+-  Fix package
+
+0.3.0 (2010-05-03)
+------------------
+
+-  View.template\_path can now hold a list of path
+-  Add {{& blah}} as an alias for {{{ blah }}}
+-  Higher Order Sections
+-  Inverted sections
+
+0.2.0 (2010-02-15)
+------------------
+
+-  Bugfix: Methods returning False or None are not rendered
+-  Bugfix: Don't render an empty string when a tag's value is 0.
+   [enaeseth]
+-  Add support for using non-callables as View attributes.
+   [joshthecoder]
+-  Allow using View instances as attributes. [joshthecoder]
+-  Support for Unicode and non-ASCII-encoded bytestring output.
+   [enaeseth]
+-  Template file encoding awareness. [enaeseth]
+
+0.1.1 (2009-11-13)
+------------------
+
+-  Ensure we're dealing with strings, always
+-  Tests can be run by executing the test file directly
+
+0.1.0 (2009-11-12)
+------------------
+
+-  First release
+
+
+License
+=======
+
+Copyright (C) 2012 Chris Jerdonek.  All rights reserved.
+
+Copyright (c) 2009 Chris Wanstrath
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/HISTORY.rst b/HISTORY.rst
deleted file mode 100644
index e03c60e..0000000
--- a/HISTORY.rst
+++ /dev/null
@@ -1,146 +0,0 @@
-History
-=======
-
-0.5.3 (TBD)
------------
-
--  Added option of raising errors on missing tags/partials:
-   ``Renderer(missing_tags='strict')`` (issue #110).
--  Added a ``parse()`` function that yields a printable, pre-compiled
-   parse tree.
--  Added support for rendering pre-compiled templates.
--  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).
--  More robust handling of byte strings in Python 3.
-
-0.5.2 (2012-05-03)
-------------------
-
--  Added support for dot notation and version 1.1.2 of the spec (issue
-   #99). [rbp]
--  Missing partials now render as empty string per latest version of
-   spec (issue #115).
--  Bugfix: falsey values now coerced to strings using str().
--  Bugfix: lambda return values for sections no longer pushed onto
-   context stack (issue #113).
--  Bugfix: lists of lambdas for sections were not rendered (issue #114).
-
-0.5.1 (2012-04-24)
-------------------
-
--  Added support for Python 3.1 and 3.2.
--  Added tox support to test multiple Python versions.
--  Added test script entry point: pystache-test.
--  Added \_\_version\_\_ package attribute.
--  Test harness now supports both YAML and JSON forms of Mustache spec.
--  Test harness no longer requires nose.
-
-0.5.0 (2012-04-03)
-------------------
-
-This version represents a major rewrite and refactoring of the code base
-that also adds features and fixes many bugs. All functionality and
-nearly all unit tests have been preserved. However, some backwards
-incompatible changes to the API have been made.
-
-Below is a selection of some of the changes (not exhaustive).
-
-Highlights:
-
--  Pystache now passes all tests in version 1.0.3 of the `Mustache
-   spec <https://github.com/mustache/spec>`_. [pvande]
--  Removed View class: it is no longer necessary to subclass from View
-   or from any other class to create a view.
--  Replaced Template with Renderer class: template rendering behavior
-   can be modified via the Renderer constructor or by setting attributes
-   on a Renderer instance.
--  Added TemplateSpec class: template rendering can be specified on a
-   per-view basis by subclassing from TemplateSpec.
--  Introduced separation of concerns and removed circular dependencies
-   (e.g. between Template and View classes, cf. `issue
-   #13 <https://github.com/defunkt/pystache/issues/13>`_).
--  Unicode now used consistently throughout the rendering process.
--  Expanded test coverage: nosetests now runs doctests and ~105 test
-   cases from the Mustache spec (increasing the number of tests from 56
-   to ~315).
--  Added a rudimentary benchmarking script to gauge performance while
-   refactoring.
--  Extensive documentation added (e.g. docstrings).
-
-Other changes:
-
--  Added a command-line interface. [vrde]
--  The main rendering class now accepts a custom partial loader (e.g. a
-   dictionary) and a custom escape function.
--  Non-ascii characters in str strings are now supported while
-   rendering.
--  Added string encoding, file encoding, and errors options for decoding
-   to unicode.
--  Removed the output encoding option.
--  Removed the use of markupsafe.
-
-Bug fixes:
-
--  Context values no longer processed as template strings.
-   [jakearchibald]
--  Whitespace surrounding sections is no longer altered, per the spec.
-   [heliodor]
--  Zeroes now render correctly when using PyPy. [alex]
--  Multline comments now permitted. [fczuardi]
--  Extensionless template files are now supported.
--  Passing ``**kwargs`` to ``Template()`` no longer modifies the
-   context.
--  Passing ``**kwargs`` to ``Template()`` with no context no longer
-   raises an exception.
-
-0.4.1 (2012-03-25)
-------------------
-
--  Added support for Python 2.4. [wangtz, jvantuyl]
-
-0.4.0 (2011-01-12)
-------------------
-
--  Add support for nested contexts (within template and view)
--  Add support for inverted lists
--  Decoupled template loading
-
-0.3.1 (2010-05-07)
-------------------
-
--  Fix package
-
-0.3.0 (2010-05-03)
-------------------
-
--  View.template\_path can now hold a list of path
--  Add {{& blah}} as an alias for {{{ blah }}}
--  Higher Order Sections
--  Inverted sections
-
-0.2.0 (2010-02-15)
-------------------
-
--  Bugfix: Methods returning False or None are not rendered
--  Bugfix: Don't render an empty string when a tag's value is 0.
-   [enaeseth]
--  Add support for using non-callables as View attributes.
-   [joshthecoder]
--  Allow using View instances as attributes. [joshthecoder]
--  Support for Unicode and non-ASCII-encoded bytestring output.
-   [enaeseth]
--  Template file encoding awareness. [enaeseth]
-
-0.1.1 (2009-11-13)
-------------------
-
--  Ensure we're dealing with strings, always
--  Tests can be run by executing the test file directly
-
-0.1.0 (2009-11-12)
-------------------
-
--  First release
-
diff --git a/LICENSE b/LICENSE
index 1943585..42be9d6 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,5 @@
 Copyright (C) 2012 Chris Jerdonek.  All rights reserved.
+
 Copyright (c) 2009 Chris Wanstrath
 
 Permission is hereby granted, free of charge, to any person obtaining
diff --git a/MANIFEST.in b/MANIFEST.in
index 56a1d52..d7b83ca 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,6 +1,7 @@
+include README.md
+include HISTORY.md
 include LICENSE
-include HISTORY.rst
-include README.rst
+include DESCRIPTION.rst
 include tox.ini
 include test_pystache.py
 # You cannot use package_data, for example, to include data files in a
diff --git a/pystache/tests/common.py b/pystache/tests/common.py
index 24b24dc..307a2be 100644
--- a/pystache/tests/common.py
+++ b/pystache/tests/common.py
@@ -22,7 +22,7 @@ PROJECT_DIR = os.path.join(PACKAGE_DIR, '..')
 SPEC_TEST_DIR = os.path.join(PROJECT_DIR, 'ext', 'spec', 'specs')
 # TEXT_DOCTEST_PATHS: the paths to text files (i.e. non-module files)
 # containing doctests.  The paths should be relative to the project directory.
-TEXT_DOCTEST_PATHS = ['README.rst']
+TEXT_DOCTEST_PATHS = ['README.md']
 
 UNITTEST_FILE_PREFIX = "test_"
 
diff --git a/setup.py b/setup.py
index 607c716..5fcae34 100644
--- a/setup.py
+++ b/setup.py
@@ -7,7 +7,25 @@ This script supports publishing Pystache to PyPI.
 This docstring contains instructions to Pystache maintainers on how
 to release a new version of Pystache.
 
-(1) Push to PyPI.  To release a new version of Pystache to PyPI--
+(1) Prepare the release.
+
+Make sure the code is finalized and merged to master.  Bump the version
+number in setup.py, etc.
+
+Generate the reStructuredText long_description using--
+
+    python setup.py prep
+
+and be sure this new version is checked in.  You must have pandoc installed
+to do this step:
+
+  http://johnmacfarlane.net/pandoc/
+
+It helps to review this auto-generated file on GitHub prior to uploading
+because the long description will be sent to PyPI and appear there after
+publishing.
+
+(2) Push to PyPI.  To release a new version of Pystache to PyPI--
 
     http://pypi.python.org/pypi/pystache
 
@@ -15,8 +33,7 @@ create a PyPI user account if you do not already have one.  The user account
 will need permissions to push to PyPI.  A current "Package Index Owner" of
 Pystache can grant you those permissions.
 
-When you have permissions, run the following (after preparing the release,
-merging to master, bumping the version number in setup.py, etc):
+When you have permissions, run the following:
 
     python setup.py publish
 
@@ -35,7 +52,7 @@ as described here, for example:
 
     http://docs.python.org/release/2.5.2/dist/pypirc.html
 
-(2) Tag the release on GitHub.  Here are some commands for tagging.
+(3) Tag the release on GitHub.  Here are some commands for tagging.
 
 List current tags:
 
@@ -52,8 +69,10 @@ Push a tag to GitHub:
 """
 
 import os
+import shutil
 import sys
 
+
 py_version = sys.version_info
 
 # Distribute works with Python 2.3.5 and above:
@@ -67,16 +86,16 @@ else:
     import setuptools as dist
     setup = dist.setup
 
-# TODO: use the logging module instead of printing.
-# TODO: include the following in a verbose mode.
-# print("Using: version %s of %s" % (repr(dist.__version__), repr(dist)))
-
 
 VERSION = '0.5.2-rc.1'  # Also change in pystache/__init__.py.
 
-HISTORY_PATH = 'HISTORY.rst'
+FILE_ENCODING = 'utf-8'
+
+README_PATH = 'README.md'
+HISTORY_PATH = 'HISTORY.md'
 LICENSE_PATH = 'LICENSE'
-README_PATH = 'README.rst'
+
+DESCRIPTION_PATH = 'DESCRIPTION.rst'
 
 CLASSIFIERS = (
     'Development Status :: 4 - Beta',
@@ -106,7 +125,52 @@ def read(path):
     finally:
         f.close()
 
-    return b.decode('utf-8')
+    return b.decode(FILE_ENCODING)
+
+
+def write(u, path):
+    """
+    Write a unicode string to a file (as utf-8).
+
+    """
+    print("Writing to: %s" % path)
+    # This function implementation was chosen to be compatible across Python 2/3.
+    f = open(path, "wb")
+    try:
+        b = u.encode(FILE_ENCODING)
+        f.write(b)
+    finally:
+        f.close()
+
+
+def prep():
+    """
+    Generate the long_description needed for setup.py.
+
+    The long description needs to be formatted as reStructuredText:
+
+      http://docs.python.org/distutils/setupscript.html#additional-meta-data
+
+    """
+    # Comments in reST begin with two dots.
+    intro = """\
+.. This file is auto-generated by setup.py, so it should not be edited.
+"""
+
+    readme_path = convert_md_to_rst(README_PATH)
+    history_path = convert_md_to_rst(HISTORY_PATH)
+
+    license = """\
+License
+=======
+
+""" + read(LICENSE_PATH)
+
+    sections = [intro, read(readme_path), read(history_path), license]
+
+    description = '\n'.join(sections)
+
+    write(description, DESCRIPTION_PATH)
 
 
 def publish():
@@ -122,19 +186,22 @@ def publish():
     os.system('python setup.py sdist upload')
 
 
-def make_long_description():
+def convert_md_to_rst(path):
     """
-    Return the long description for the package.
+    Convert the given file from markdown to reStructuredText.
+
+    Returns the new path.
 
     """
-    license = """\
-License
-=======
+    root, ext = os.path.splitext(path)
+    new_path = root + ".temp.rst"
+    print("Converting: %s to %s" % (path, new_path))
 
-""" + read(LICENSE_PATH)
+    # Pandoc uses the UTF-8 character encoding for both input and output.
+    command = "pandoc --write=rst --output=%s %s" % (new_path, path)
+    os.system(command)
 
-    sections = [read(README_PATH), read(HISTORY_PATH), license]
-    return '\n\n'.join(sections)
+    return new_path
 
 
 # We follow the guidance here for compatibility with using setuptools instead
@@ -183,11 +250,20 @@ PACKAGES = [
 
 def main(sys_argv):
 
-    if sys.argv[-1] == 'publish':
+    # TODO: use the logging module instead of printing.
+    # TODO: include the following in a verbose mode.
+    print("pystache: using: version %s of %s" % (repr(dist.__version__), repr(dist)))
+
+    command = sys_argv[-1]
+
+    if command == 'publish':
         publish()
         sys.exit()
+    elif command == 'prep':
+        prep()
+        sys.exit()
 
-    long_description = make_long_description()
+    long_description = read(DESCRIPTION_PATH)
     template_files = ['*.mustache', '*.txt']
 
     setup(name='pystache',
@@ -198,6 +274,7 @@ def main(sys_argv):
           author='Chris Wanstrath',
           author_email='chris@ozmm.org',
           maintainer='Chris Jerdonek',
+          maintainer_email='chris.jerdonek@gmail.com',
           url='http://github.com/defunkt/pystache',
           install_requires=INSTALL_REQUIRES,
           packages=PACKAGES,