I am -1 on this on the basis that the services mentioned also happily
support restructured text READMEs
On 5/2/2016 12:40, Nick Timkovich wrote:
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
_______________________________________________
Distutils-SIG maillist - Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig
_______________________________________________
Distutils-SIG maillist - Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig