Broken package description on PyPI

[keikoro]

I have no idea where to report errors on PyPI pages describing packages, so I thought I'd start here:

All the links in the PyPI description of twitter are broken; it'd be great if they could be fixed to make that info page more user-friendly.

Aditionally it'd be very helpful if this GitHub repo were actually linked to from the PyPI page so people interested in contributing would quickly find their way here. – It took myself quite a bit of googling to arrive here (the name of the package doesn't really help with matters...).

[keikoro]

Hmm, just had another look and it seems the description over on PyPI is a copy-paste of a Markdown file (possibly the repo's README) and that's why the links appear broken?

If it's too much work to always update the description there as well, wouldn't it make more sense to keep it brief but properly formatted and just refer (and link) to the README on here for further information?

[hugovk]

You're right, the description at PyPI comes from README, but at the moment is done automatically rather than manually copied and pasted, from this:

long_description=open("./README", "r").read(),

https://github.com/sixohsix/twitter/blob/master/setup.py#L19

[keikoro]

I see!

So for it to display properly, the Markdown woud have to be converted to plain text (or possibly HTML? not sure which imports are allowed on PyPI) first, and a link back to here would have to be added separately (e.g. via a separate file... that gets concatenated with the README, I suppose?).

Hmm. Thanks for the info.

[hugovk]

Yes, something like that.

setup.py could have a function to convert the badges from Markdown to HTML or RST or even delete them.

Here's some examples:
https://bitbucket.org/pypa/pypi/issues/148/support-markdown-for-readmes#comment-23875412
http://stackoverflow.com/a/23265673/724176

[keikoro]

Yeah, I was doing a bit of research on my own and stumbled upon it being done with rst files.

I won't have time to look into this more until late January, but as no-one seemed to have taken issue with this so far I guess that won't be a problem. (; I'm definitely interested in fixing this, though!

[keikoro]

So, I'm currently going through issues I opened and I did something with reStructuredText for the first time today, and it turns out that GitHub can display those as well.

Now I'm not sure which method would be preferable: to convert the original README done with Markdown to an .rst file and replace the old file with that new one or to add a function to setup.py that does the conversion just for PyPI, like @hugovk suggested.

What do you think, @RouxRC @sixohsix?

[RouxRC]

I guess both work.
Although, since initially the readme was generated from comments in the api.py code, even though we haven't been doing that in a while, we've been keeping the texts in sync between the two, so I guess in case we end up doing this again at some point, it would be best to generate the rst from the md

[keikoro]

Interesting, I only realised now that the .md file links to the README file (without file ending). Was the .md only added to the repo for GitHub? Because I don't think GitHub needs the file ending...

I've meanwhile also found readme_renderer, a tool developed for the new version of PyPI.

Anyway, I've now added the code required to have the README converted to .rst and will make a PR in a bit. I dunno how you want the requirements for maintainers handled though, see the notes in this comment by the user who originally provided the solution.

[RouxRC]

Thanks, mergin it now!
I don't personally have an opinion on maintainers requirements, only @sixohsix can update pypy's repository anyways, so we'll leave it at him ;)