Obtain package description from README.md (Markdown)

[ntninja]

Hi! I've been following for the last couple of months and I like how this project is developing. Big thumbs up! 👍

We're starting to seriously consider migrating our project to flit, but there is one caveat: We currently use a README.md (vs an README.rst) and on-the-fly convert this to ReStructuredText when uploading to PyPI, while this solution is sub-optimal in several ways, it does work. Is there any way to do something similar with flit?

May be related to: #98

[takluyver]

There's actually a hidden feature in flit: if you have pypandoc & pandoc installed, and you specify a file with a .md extension, it will convert it to rst prior to uploading.

The reasons it's hidden for now are that I don't really want to support installing pandoc, and I don't know if the rst it produces reliably satisfies PyPI. So it's easier to tell people to write rst. But if you prefer markdown, you can do it that way.

[ntninja]

Thanks for this answer! Totally not what I was expecting! 🙂

I totally understand that you don't want to publically advertise a feature as dependecy-heavy as this one (I wouldn't either, not for this), but may I ask if you intend to keep this feature stable and in it's current form for the forseeable future? Even if don't intend to document it, it would be nice to have your word that this won't just be silently dropped one day.

Hopefully recommonmark can become a suitable alternative to pandoc for this one day…

Anyway, I just gave the first serious testing to flit and I already love it. 😍
Awesome job on this!

[takluyver]

Super! 😄

I don't see any reason to get rid of the hidden pandoc feature, and if I ever do, I'll do so with a deprecation cycle unless there's a really good reason that's not practical.

It's possible that one day Warehouse (the new PyPI) will directly support markdown descriptions, so we won't need the conversion in flit. It sounds like the current sticking point is how to specify the description format in the metadata. pypi/warehouse#869

[takluyver]

Actually, I didn't read carefully enough - there is already consensus on the metadata; now it's waiting for tools to support it - crucially, this PR: pypa/readme_renderer#51

[ntninja]

Thanks for the links! I really didn't expect this was being worked on when I opened this issue yesterday!

So the prefered migration path for this feature is for Description-Content-Type to become natively supported by Warehouse & Legacy-PyPI, which will then allow flit to simply upload any .md file using the right media-type?

[takluyver]

Yup, that's right. I think we should be able to make it transparent to the user when that happens, by taking the .md extension to mean that Description-Content-Type is text/markdown. It will probably start warning/erroring if the extension isn't one of .md, .rst or .txt.

I think it's fairly low down the list of priorities for Warehouse, so the pypandoc workaround will probably stick around for a while.

[ntninja]

Ok, thanks for your help and explantions! I think this specific issue was adressed! 👍

(I changed the title so that other people can easily find this if they are looking for something similar.)