[Distutils] README.rst vs DESCRIPTION.rst

[Ian Cordasco]

On Sun, Sep 27, 2015 at 1:18 PM, Ionel Cristian Mărieș
<contact at ionelmc.ro> wrote:
>
> On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler
> <guettliml at thomas-guettler.de> wrote:
>>
>>
>> OK, the sample project is not the definitive guide line.
>> Where can I find the definitive guide line?
>
>
> I don't think there can be a "definitive guide line". Unlike the core
> language the packaging part of Python is a messy soup of different and often
> competing ideas, styles and tools.
>
> So you cannot have an definitive or objective guide for something that's
> subjective in nature.
>
> About the README vs DESCRIPTION - ask yourself, what would you use README
> for then? I believe that's absolutely nothing. You only need one. :-)

I tend to disagree. Your project's long description doesn't need
detailed instructions on how to start contributing, reporting bugs,
etc. That should be in your README and documentation/project website.
I don't think that having two separate files is a problem. You could
even use the include directive from reStructuredText so that your
README includes your description without duplicating the content.

I haven't previously followed this guideline, but I think I'm going to
start. I quite like it.