Merge branch 'convert-docs-to-markdown' into development:

Converted README and HISTORY to markdown to allow use of GitHub
pages feature.

1 files changed, 125 insertions, 22 deletions

diff --git a/setup.py b/setup.py
index 607c716..792a6d1 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,20 @@ 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 = 'setup_description.rst'
+
+TEMP_REST_EXTENSION = '.temp.rst'
+
+PREP_COMMAND = 'prep'
 
 CLASSIFIERS = (
     'Development Status :: 4 - Beta',
@@ -106,15 +129,83 @@ 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 make_temp_path(path):
+    root, ext = os.path.splitext(path)
+    temp_path = root + TEMP_REST_EXTENSION
+    return temp_path
+
+
+def make_description_file(target_path):
+    """
+    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, target_path)
+
+
+def prep():
+    make_description_file(DESCRIPTION_PATH)
 
 def publish():
     """
     Publish this package to PyPI (aka "the Cheeseshop").
 
     """
-    answer = raw_input("Are you sure (yes/no)?")
+    temp_path = make_temp_path(DESCRIPTION_PATH)
+    make_description_file(temp_path)
+
+    if read(temp_path) != read(DESCRIPTION_PATH):
+        print("""\
+Description file not up-to-date: %s
+Run the following command and commit the changes--
+
+    python setup.py %s
+""" % (DESCRIPTION_PATH, PREP_COMMAND))
+        sys.exit()
+
+    print("Description up-to-date: %s" % DESCRIPTION_PATH)
+
+    answer = raw_input("Are you sure you want to publish to PyPI (yes/no)?")
 
     if answer != "yes":
         exit("Aborted: nothing published")
@@ -122,19 +213,21 @@ 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
-=======
+    temp_path = make_temp_path(path)
+    print("Converting: %s to %s" % (path, temp_path))
 
-""" + read(LICENSE_PATH)
+    # Pandoc uses the UTF-8 character encoding for both input and output.
+    command = "pandoc --write=rst --output=%s %s" % (temp_path, path)
+    os.system(command)
 
-    sections = [read(README_PATH), read(HISTORY_PATH), license]
-    return '\n\n'.join(sections)
+    return temp_path
 
 
 # We follow the guidance here for compatibility with using setuptools instead
@@ -183,11 +276,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_COMMAND:
+        prep()
+        sys.exit()
 
-    long_description = make_long_description()
+    long_description = read(DESCRIPTION_PATH)
     template_files = ['*.mustache', '*.txt']
 
     setup(name='pystache',
@@ -198,6 +300,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,