search

pypa / packaging.python.org

Python Packaging User Guide
http://packaging.python.org
1.45k stars 932 forks source link

Update PyPI README instructions #971

Open bhrutledge opened 3 years ago

bhrutledge commented 3 years ago

While reviewing https://github.com/pypa/packaging.python.org/pull/969, I noticed that making-a-pypi-friendly-readme.rst uses setup.py, while packaging-projects.rst recommends setup.cfg.

I think the README guide should be updated to use setup.cfg. I think it'd also be nice to link to making-a-pypi-friendly-readme from other relevant guides, such as packaging-projects and distributing-packages-using-setuptools.

Somewhat related: https://github.com/pypa/packaging.python.org/issues/887

CAM-Gerlach commented 2 years ago

Indeed. The "Include your readme in the package's metadata" section can be almost entirely elided and replaced with just a few lines instructing package authors how to set

long_description = file: README.md
long_description_content_type = text/markdown

The repeated reminders to upgrade packaging tools to versions that are long-supported across the ecosystem is likewise no longer needed, especially since PEP 518 takes care of that anyway and packaging tools don't need to be installed in the user's working environment at all.

The "Validating reST Markup" section could be simplified by using pipx to install and run Twine in one go, though that's somewhat more opinionated

chrysle commented 1 year ago

After setup.cfg guidance has been entirely replaced with pyproject.toml in #1031 in the linked packaging projects guide, I think the README instructions should adapt to that.