long_description renders improperly on PyPI

[mblayman]

Steps to reproduce

View https://pypi.python.org/pypi/djangorestframework/3.3.3 on PyPI.

Expected behavior

Rendered HTML that includes links, headings, and the like.

Actual behavior

Raw reST markup appears in a non-monospace font.

I looked at the setup.py and observed that the project does not actually use the long_description field. I think PyPI is trying to convert the README.md to reST and failing. Since PyPI does not support Markdown (see https://bitbucket.org/pypa/pypi/issues/148/support-markdown-for-readmes), maybe an explicit long_description directing users to the proper documentation would be appropriate.

[xordoquy]

pandoc has been configured to provide a long desc which should override the README.md.
We need to investigate why this didn't work for 3.3.3.

[mblayman]

I'll add that this is not unique for 3.3.3. The issue goes back to 3.1.2. Prior to that, it appears that the README content was not included in the long_description. Unless something has changed about PyPI rendering of the long_description, maybe this never worked properly. shrug

Should I be reporting this somewhere else? I'm new to reporting issues for this project. It seems like this is a valid issue so I'm unclear on why it is closed. Is there some further action I can take to help this get fixed?

[xordoquy]

This issue is already reported as #3817

[mblayman]

Cool, thanks for clarifying!

[GitRon]

Sorry to dig this up but it seems that the Readme is - again - not rendered properly: https://pypi.org/project/djangorestframework/

setup.py looks good though... Really odd.

@xordoquy

[carltongibson]

Hmm. OK. Something has gone wrong there. Thanks for the report. I’ll look into it next week.

[rpkilby]

Also, twine check dist/* passes on master and the 3.9.3 tag. Note that the last working readme render was 3.9.0

[rpkilby]

The diff between 3.9.0...3.9.1 doesn't point out anything obvious as to why this would fail. I've also successfully rendered the readme locally (using the snippet from pypa/readme_renderer#117), so it's not clear to me why this is failing on PyPI.

[rpkilby]

Ah, finally figured it out. A lot of additional info in pypa/twine#425, but the short version is that we were using an outdated wheel v0.30.0 to create the distributions, which doesn't support metadata 2.1 and the long_description_content_type option.

The fix is to ensure we run twine check dist/* to the publish command, which will complain when the readme is malformed. e.g., here's the output when wheel v0.30.0 is used:

Checking distribution dist/djangorestframework-3.9.3-py3-none-any.whl: warning: `long_description_content_type` missing.  defaulting to `text/x-rst`.
Failed
The project's long_description has invalid markup which will not be rendered on PyPI. The following syntax errors were detected:
line 73: Warning: Definition list ends without a blank line; unexpected unindent.
Checking distribution dist/djangorestframework-3.9.3.tar.gz: Passed