[Distutils] Basic Markdown Readme Support

[Nick Timkovich]

Markdown READMEs are becoming increasingly ubiquitous for many projects.
GitHub, GitLab, Bitbucket, among others, happily detect .md readme files
and render them in their web interfaces. rST is nice, but is generally
overkill for single-page documents (as opposed to more intricate
documentation). To get something done sooner, rather than later, I'd prefer
to come up with a two-phase solution, one narrow and "opt-in" (status-quo
for all existing packages unless the maintainer does something) for quick
implementation with hopefully minimal pushback. The other, later,
not-proposed-here, could be more feature-rich/heuristic.

So, to get Markdown supported in some form, here's some talking points to
debate:

* Add a "long_description_filename" to setup (suggested by @msabramo/GH
[1]), which does the usual boilerplate "[codecs.]open(x, 'r',
encoding=y).read()". To determine the format look at an additional
"long_description_content_type" field (if provided), otherwise look at the
file extension and assume/require UTF-8.

    * As an alternative, if there is no long_description, and the fall-back
to README.rst fails, look for README.md and grab that. Such a strategy
wouldn't be fully opt-in, however.

* Markdown (just like reStructuredText) allows arbitrary HTML to be added.
The renderer must then be upstream of the (existing) clean (with bleach)
step.

* [Optional]: Use common extensions provided by the PyPI/Markdown library
to support GFM/SO stuff: fenced_code, smart_strong, nl2br

Nick Timkovich
Amaral Lab, Northwestern University

[1]: https://github.com/pypa/readme_renderer/pull/3#issuecomment-72302732
[2]: https://github.com/pypa/readme_renderer/pull/3#issuecomment-66569248
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20160502/3651a0ac/attachment.html>