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