[Distutils] README.rst vs DESCRIPTION.rst

Thomas Güttler guettliml at thomas-guettler.de
Sun Sep 27 19:05:56 CEST 2015

Am 27.09.2015 um 13:06 schrieb Paul Moore:
> 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.

I don't see a use case to have both files.

> 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. 

OK, the sample project is not the definitive guide line.
Where can I find the definitive guide line?

> 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.

I am not a beginner. From time to time a try to set on beginner
glasses and try to see the world with beginner eyes. I guess
I am good at this. Maybe that's because I am the father of disabled child.

I guess a beginner wants **one** file. And a beginner wants this
file to be rendered on the frontpage if he uses github.

> 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.

I know.

> 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!! :-))

Yes it is not a big deal. It is just one small stone laying around
on the road to make python more easy for beginners.

Paul, please tell me your choice: README.rst or DESCRIPTION.rst. Which
one do you prefer to be used in setup.py of the example project?

  Thomas Güttler


More information about the Distutils-SIG mailing list