Description of how to set a project description doesn't mention that you have to use "twine"

I looked at the page for ConceptNet on the new PyPI, and saw that it didn’t have much of a description.

I went to the “manage” page and saw this message: https://imgur.com/a/pSlvUl6

I read the documentation it linked, and read about long_description and long_description_content_type, so I put those in setup.py, incremented the version number, and ran python setup.py sdist upload, like I always have.

Whoops. It turns out that you can’t use long_description_content_type unless you’re using Twine and have a bunch of other dependencies up to date, so the formatting is still garbage: https://pypi.org/project/ConceptNet/

I eventually learned that Twine is required by Googling a lot and finding it several paragraphs down on someone’s blog post: https://dustingram.com/articles/2018/03/16/markdown-descriptions-on-pypi . Yes, the packaging documentation now says to use Twine, but very far from the place that PyPI linked me to – and I had no reason to know that the command had changed from python setup.py sdist upload or that there was imperfect compatibility with the old command. I don’t just re-read the entire packaging guide every week for fun.

The message about how to set your project description should mention Twine, or ideally, PyPI should be able to fix releases created with python setup.py sdist upload.

[theacodes]

I wonder if it’s worthwhile to duplicate the warning that’s on the index for distutils across all of its pages, notably, this part:

This guide only covers the basic tools for building and distributing extensions that are provided as part of this version of Python. Third party tools offer easier to use and more secure alternatives. Refer to the quick recommendations section in the Python Packaging User Guide for more information.

Having that on the index is great, but all too often users find subpages via organic search and never even realize they’re reading something that is literally rigged for failure.

[theacodes]

For what it’s worth, the notice is already in the Python docs as of 3.6: https://docs.python.org/3.6/distutils/index.html.

I agree with @rspeer here. Our little notice in Warehouse for project description should mention that Twine is basically necessary for full description support. I’ll send a PR for that momentarily.