[Distutils] Basic Markdown Readme Support

Nick Coghlan ncoghlan at gmail.com
Tue May 3 09:47:58 EDT 2016

On 3 May 2016 at 23:18, Fred Drake <fred at fdrake.net> wrote:
> My perspective, for what it's worth, is that while I find Markdown a
> horrible pain, there are a lot of people who pick it up before picking
> up Python, and tools like GitHub and BitBucket  encourage (and make it
> easier to add) README.md to a project. For someone who isn't familiar
> with reStructuredText, it's an easier on-ramp.
> So while I'm all for encouraging developers to prefer
> reStructuredText, I'm in favor of supporting Markdown as a
> long_description format. The format for a README file just doesn't
> seem such a big deal that alienating potential community members is
> worth it.

Exactly. The lack of support for Markdown README files is mainly a
matter of a historical quirk of the way the PyPI metadata upload API
works making this way more work to implement than it seems at first
glance, the current PyPI codebase being sufficiently fragile that we
actively avoid changing it, and getting Warehouse to the point of
being sufficiently feature complete for it to take over primary
service responsibilities being a long hard slog for the folks working
on it (it's a lot harder to find volunteers interested in working on
paying down technical debt than it is to find folks that want to work
on new user facing features).

However, this SO answer provides some ideas on ways to convert from
Markdown to reStructured Text when producing the sdist metadata, or to
derive a checked in .rst file from a README.md file:

It is also seems plausible to me that a client-side solution could be
designed that allowed the description metadata stored in the sdist to
be overridden when uploading to PyPI (i.e. the description in PKG-INFO
could be Markdown, but the upload tool could use pypandoc to convert
that to reStructuredText in the uploaded metadata). I'm not sure if
Donald would be open to that in twine (presumably via an extra to
avoid having pypandoc as a standard dependency), but client-only
changes are generally an easier pitch than changes to the interfaces
between client tools and PyPI.


Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Distutils-SIG mailing list