[Distutils] README.rst vs DESCRIPTION.rst

[Paul Moore]

On 27 September 2015 at 18:05, Thomas Güttler
<guettliml at thomas-guettler.de> wrote:
>> 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 think you're misunderstanding what I meant by "definitive". It's a
guideline, yes. But guidelines aren't definitive (by definition) -
they are for guidance, and people can use something different if they
prefer.

The nearest you'll find to a "definitive" answer is in the packaging
user guide, which says to supply a README.rst, and a long_description
argument to setup.py. It doesn't say whether the two should be
required to have the same content (IMO, they shouldn't) or how you
supply the data for the long_description argument. The sample project
(referred to from packaging.python.org) chooses to implement
long_description by reading it from a file called DESCRIPTION.rst,
because that's what seemed convenient to me when I wrote it. But
you're welcome to do something different if you prefer - and if you do
so you'll still be in line with the guidelines in the packaging user
guide (if conforming to those guidelines matters to you).

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

I preferred DESCRIPTION.rst. That's why I created it with that name
:-) Mainly because I don't believe that a project README and the
package's long_description are necessarily the same thing.

Now, I mostly don't care.
Paul