[Distutils] README.rst vs DESCRIPTION.rst

Paul Moore p.f.moore at gmail.com
Sun Sep 27 13:06:12 CEST 2015

On 27 September 2015 at 11:20, Thomas Güttler
<guettliml at thomas-guettler.de> wrote:
> Any good reason to **not** use README.rst but a different
> name like DESCRIPTION.rst?

If I recall, the reason for using DESCRIPTION.rst is that README.rst
is used by other tools (for example, github) and it's not immediately
obvious that the same content is applicable for both cases.

In practice, the sample project is not expected to be treated as
definitive, so I don't think it matters that much if people use a
different name. I'd rather the example uses DESCRIPTION.rst, as that
way beginners don't end up confused if they find their package
long_description being used in places they didn't intend. Conversely,
it's relatively easy to see that if they want to use README.rst for
the file, all they have to do is change the name and edit setup.py in
one place.

It's not a big deal either way, though (and probably not even worth
the time I spent writing this email to debate about it!! :-))

More information about the Distutils-SIG mailing list