Guidlines for making a PyPI-friendly readme

[ddbeck]

A warehouse issue brought up the idea of documenting how to format code in READMEs for PyPI. Rather than covering code formatting alone, I thought it might be useful to have a section that covers setting the contents of a project's PyPI home page:

• explaining where the content of a project's page on PyPI comes from (i.e., long_description)
• setting the contents of long_description to the content of a project's README file (like the pypa sample project does)
• using ReST to format the document and specifically calling attention to the PyPI-specific case of pygments lexers

Before I started writing, I thought I would open this issue for feedback or additional ideas.

[dstufft]

Note: you can test a long_description using the exact same code that PyPI (and Warehouse) uses (modulo version numbers) using:

$ pip install readme
$ python setup.py check -r -s

[brainwane]

@njsmith suggested it might also be good to link to https://pypi.python.org/pypi/pyroma .

[brainwane]

I now see that https://packaging.python.org/tutorials/distributing-packages/?highlight=https#uploading-your-project-to-pypi does mention readme_renderer.

I do think a bit more explanation, mapping bits of the README to bits of a PyPI project detail page, would be useful.

[brainwane]

The packaging and distribution tutorial currently says:

All projects should contain a readme file that covers the goal of the project. The most common format is reStructuredText with an “rst” extension, although this is not a requirement.

I think that right now we should just say it is a requirement, to simplify the experience for users, till the multiple steps laid out in pypi/warehouse#869 (comment) are completed. This would also reduce conflict with the sample project README which says that it should be written in reStructuredText.

This would reduce confusion. I was advising a person today who was trying out the new PyPI who asked,

The docs say that rst isn't the only format for readmes, but don't say what other formats are accepted. Can it handle markdown?

Until we can confidently list what other formats will render well, let's just advise people to use .rst.

[di]

I think the docs are implying that plaintext is also an option, if users don't want to use reStructuredText.

[ncoghlan]

Right, the two currently fully supported formats are plain text (*.txt) and reStructuredText (*.rst). It works out that way because PyPI attempts to render with https://pypi.python.org/pypi/readme_renderer and if that fails, it treats the description as plain text.

*.md doesn't render as ReST, so it ends up being handled as plain text.

[ncoghlan]

Also worth noting: PEP 566 has been accepted, so I'd expect Markdown to be supported properly over the next couple of months (pypi.python.org will still render them as plain text, but pypi.org will render them properly)

[engnadeau]

@ncoghlan do you have a branch/PR/issue we can follow for Markdown support?

[di]

@nnadeau You can follow pypi/warehouse#869, which I will close once it's possible to publish a package with a Markdown description with some subset of packaging tools.

[brainwane]

@di posted it in pypi/warehouse#869 but it's worth pointing to here as well: with releases or pre-releases available of all the tools in the packaging and distro toolchain, you can now build and upload an sdist to Warehouse with a Markdown README!

Followups:

• Updates for PEP 566 wheel#231
• Test PEP 566 features pypi/warehouse#3299
• supporting GitHub-flavored Markdown as Description-Content-Type packaging-problems#126

[brainwane]

@ddbeck If you are interested in writing "make a PyPI-friendly README" as a Guide, I for one would welcome it.

[ddbeck]

@brainwane good timing on reminding me of this! I actually have some time for this either tomorrow or Monday. Feel free to nudge me about it if there's no progress by Tuesday. :-)

[ddbeck]

OK, I didn't make as much progress on this I would've liked. I'll return to this in a couple of days. In the meantime, here's the outline I'm working from:

Title: Making a PyPI-friendly README

• Why you would want a README and where it shows up
• Choosing between a README.rst, README.md, or README.txt file
• Setting long_description and long_description_content_type
• Suggest resources for README content:
  • matiassingers/awesome-readme
  • ddbeck/readme-checklist (self-link, I admit it)
  • etc. (open to suggestions)
• Testing that your README renders (with pypa/readme_renderer)

[ddbeck]

OK, I've opened a PR to add a guide. I ultimately did not cover testing README rendering because the setup.py check doesn't seem to check Markdown yet. But maybe it's something we can cover later.

[brainwane]

Per pypi/warehouse#3438 (comment) I would love for https://packaging.python.org/guides/making-a-pypi-friendly-readme/ to mention the minimum versions of these tools folks will need:

• pkginfo>=1.4.2
• twine>=1.11.0
• setuptools>=38.6.0
• wheel>=0.31.0

[di]

I've already made a separate issue for that: #481

Also should not that the pkginfo requirement is satisfied by upgrading twine, so we probably don't need to explicitly mention it.

[ddbeck]

OK, the README guide merged and the other issue is open so I'm going to close this. Thanks, everyone!