Migrated README to Markdown (PEP 566)

MANIFEST.in

@@ -1,3 +1,6 @@
+# Include the README
+include *.md
+
 # Include the license file
 include LICENSE.txt
 

README.md

@@ -0,0 +1,37 @@
+# A sample Python project
+
+A sample project that exists as an aid to the [Python Packaging User
+Guide][packaging guide]'s [Tutorial on Packaging and Distributing
+Projects][distribution tutorial].
+
+This project does not aim to cover best practices for Python project
+development as a whole. For example, it does not provide guidance or tool
+recommendations for version control, documentation, or testing.
+
+[The source for this project is available here][src].
+
+Most of the configuration for a Python project is done in the `setup.py` file,
+an example of which is included in this project. You should edit this file
+accordingly to adapt this sample project to your needs.
+
+----
+
+This is the README file for the project.
+
+The file should use UTF-8 encoding and can be written using
+[reStructuredText][rst] or [markdown][md use] with the appropriate [key set][md
+use]. It will be used to generate the project webpage on PyPI and will be
+displayed as the project homepage on common code-hosting services, and should be
+written for that purpose.
+
+Typical contents for this file would include an overview of the project, basic
+usage examples, etc. Generally, including the project changelog in here is not a
+good idea, although a simple “What's New” section for the most recent version
+may be appropriate.
+
+[packaging guide]: https://twitter.com/mcclure111/status/975031304742895616
+[distribution tutorial]: https://twitter.com/mcclure111/status/975031304742895616
+[src]: https://twitter.com/mcclure111/status/975031304742895616
+[rst]: https://twitter.com/mcclure111/status/975031304742895616
+[md]: https://tools.ietf.org/html/rfc7764#section-3.5 "CommonMark variant"
+[md use]: https://packaging.python.org/specifications/core-metadata/#description-content-type-optional

setup.py

@@ -14,7 +14,7 @@
 here = path.abspath(path.dirname(__file__))
 
 # Get the long description from the README file
-with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
+with open(path.join(here, 'README.md'), encoding='utf-8') as f:
     long_description = f.read()
 
 # Arguments marked as "Required" below must be included for upload to PyPI.
@@ -57,6 +57,18 @@
     # https://packaging.python.org/specifications/core-metadata/#description-optional
     long_description=long_description,  # Optional
 
+    # Denotes that our long_description is in Markdown; valid values are
+    # text/plain, text/x-rst, and text/markdown
+    #
+    # Optional if long_description is written in reStructuredText (rst) but
+    # required for plain-text or Markdown; if unspecified, "applications should
+    # attempt to render [the long_description] as text/x-rst; charset=UTF-8 and
+    # fall back to text/plain if it is not valid rst" (see link below)
+    #
+    # This field corresponds to the "Description-Content-Type" metadata field:
+    # https://packaging.python.org/specifications/core-metadata/#description-content-type-optional
+    long_description_content_type='text/markdown',  # Optional (see note above)
+
     # This should be a valid link to your project's main homepage.
     #
     # This field corresponds to the "Home-Page" metadata field: