Re: [Distutils] README.rst vs DESCRIPTION.rst

[Thomas Güttler]

one week has passed. I check the feedback. Most people want one README.rst.

I see the file was already updated: 
https://github.com/pypa/sampleproject/commit/e7de7861963274595c5b3b0d6942e35ce5a733bc

Issue solved.

Thank you Carl Meyer!

Regards,
  Thomas Güttler

Am 27.09.2015 um 12:20 schrieb Thomas Güttler:
> Zen of Python:
> 
>There should be one-- and preferably only one --obvious way to do it.
> 
> I would like to find a default for the description file of a python package.
> 
> The sampleproject uses DESCRIPTION.rst
> https://github.com/pypa/sampleproject/blob/master/setup.py
> 
> But I guess it is more common to use README.rst.
> For example django uses this file name.
> 
> Any good reason to **not** use README.rst but a different
> name like DESCRIPTION.rst?
> 
> Of course anyone can use the name he wants. I just want an agreement
> for the name to make life easier for newcomers.
> 
> I will check this mail thread in a week or two and write
> a pull request to https://github.com/pypa/sampleproject/blob/master/setup.py
> if there is an agreement.
> 
> If an agreement was found, which other documents should be updated?
> 
> Regards,
>Thomas Güttler
> 
> 
> 
> 
> 


-- 
http://www.thomas-guettler.de/
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Chris Barker]

On Mon, Sep 28, 2015 at 11:19 AM, Matthew Iversen 
wrote:

> For example, the two are different for flask, virtualenv, setuptools,
> sopel, numpy
>

these are some pretty significant, complex packages.

I have trouble finding an objective reasoning that one method is to be
> objectively preferred over the other.
>

No one is suggesting reducing flexibility here. The topic under discussion
is what should be recommended and demonstrated for newbies, and the
simplest reasonable thing to do there the better - one Readme.rst seems the
obvious answer for that.


We always want to balance this with keeping `sampleproject` as simple as
> possible to make it practical and
> immediately useful, rather than overly technical.
>

Exactly.

-CHB



-- 

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR(206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115   (206) 526-6317   main reception

chris.bar...@noaa.gov
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Marcus Smith]

although I can see the value of distinguishing a description vs readme
file,  I can also see that it's confusing enough to make me want the sample
project to just have a readme for simplicity  (and maybe just mention the
distinction as a possibility)

I opened an issue here  https://github.com/pypa/sampleproject/issues/31

I'd inclined to merge the change if someone posted a PR, or eventually get
to it myself



On Mon, Sep 28, 2015 at 8:18 AM, Chris Barker - NOAA Federal <
chris.bar...@noaa.gov> wrote:

>
>
> Sent from my iPhone
>
> On Sep 27, 2015, at 11:19 AM, Ionel Cristian Mărieș 
> wrote:
>
>
> On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler <
> guettliml@thomas-guettler. 
> ​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.
>
>
> Which is EXACTLY why there should be one set of best-practices
> recommendations that are the same in all the "official" docs.
>
> I think one Readme.rst is the way to go.
>
> If you want to provide contribution guidelines, etc. they should be in a
> separate locations, referenced by the Readme.
>
> -Chris
>
>
>
> 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. :-)
>
>
>
> Thanks,
> -- Ionel Cristian Mărieș, http://blog.ionelmc.ro
>
> ___
> Distutils-SIG maillist  -  Distutils-SIG@python.org
> https://mail.python.org/mailman/listinfo/distutils-sig
>
>
> ___
> Distutils-SIG maillist  -  Distutils-SIG@python.org
> https://mail.python.org/mailman/listinfo/distutils-sig
>
>
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Chris Barker - NOAA Federal]

Sent from my iPhone

On Sep 27, 2015, at 11:19 AM, Ionel Cristian Mărieș 
wrote:


On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler 
​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.


Which is EXACTLY why there should be one set of best-practices
recommendations that are the same in all the "official" docs.

I think one Readme.rst is the way to go.

If you want to provide contribution guidelines, etc. they should be in a
separate locations, referenced by the Readme.

-Chris



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



Thanks,
-- Ionel Cristian Mărieș, http://blog.ionelmc.ro

___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Ionel Cristian Mărieș]

On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler <
guettl...@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. :-)



Thanks,
-- Ionel Cristian Mărieș, http://blog.ionelmc.ro
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Thomas Güttler]

Am 27.09.2015 um 13:06 schrieb Paul Moore:
> On 27 September 2015 at 11:20, Thomas Güttler
>  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?

Regards,
  Thomas Güttler


-- 
http://www.thomas-guettler.de/
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Paul Moore]

On 27 September 2015 at 18:05, Thomas Güttler
 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
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Ian Cordasco]

On Sun, Sep 27, 2015 at 1:18 PM, Ionel Cristian Mărieș
 wrote:
>
> On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler
>  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.
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Ian Cordasco]

On Sun, Sep 27, 2015 at 4:55 PM, Ionel Cristian Mărieș
 wrote:
>
> On Mon, Sep 28, 2015 at 12:20 AM, Ian Cordasco 
> wrote:
>>
>> Your project's long description doesn't need
>> detailed instructions on how to start contributing, reporting bugs,
>> etc.
>
>
> What would you put in README then?
>
> For contribution/bucktracker guide CONTRIBUTING.rst/md is a better place -
> GitHub loves it. But who cares, no one uses GitHub nowdays :)

Ah, the patented sarcasm that's always so helpful.

The README is typically (harkening back to pre-GitHub days) where one
lays out the relevant information for other developers and for users
in one easy to find place. Looking for the contributing guidelines? Go
read the CONTRIBUTING file. Looking for how to build the project on X
operating system? Go read X file. When well designed, this can still
be the front page of a project for the websites that display it as
such (GitHub, BitBucket, GitLab, etc.). Take for example:
https://gitlab.com/cryptsetup/cryptsetup/blob/master/README.md. It's
description lives there, sure, but there's a lot more information
there than that.

All of that said, as Paul said, it's a guideline. Just like PEP-0008.
Follow it, or don't. There's not much point in arguing this further.
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Ionel Cristian Mărieș]

On Mon, Sep 28, 2015 at 12:20 AM, Ian Cordasco 
wrote:

> Your project's long description doesn't need
> detailed instructions on how to start contributing, reporting bugs,
> etc.
>

​What would you put in README then?

For contribution/bucktracker guide CONTRIBUTING.rst/md is a better place -
GitHub loves it. But who cares, no one uses GitHub nowdays :)​



Thanks,
-- Ionel Cristian Mărieș, http://blog.ionelmc.ro
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

[Distutils] README.rst vs DESCRIPTION.rst

[Thomas Güttler]

Zen of Python:

  There should be one-- and preferably only one --obvious way to do it.

I would like to find a default for the description file of a python package.

The sampleproject uses DESCRIPTION.rst
https://github.com/pypa/sampleproject/blob/master/setup.py

But I guess it is more common to use README.rst.
For example django uses this file name.

Any good reason to **not** use README.rst but a different
name like DESCRIPTION.rst?

Of course anyone can use the name he wants. I just want an agreement
for the name to make life easier for newcomers.

I will check this mail thread in a week or two and write
a pull request to https://github.com/pypa/sampleproject/blob/master/setup.py
if there is an agreement.

If an agreement was found, which other documents should be updated?

Regards,
  Thomas Güttler





-- 
http://www.thomas-guettler.de/
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] README.rst vs DESCRIPTION.rst

[Paul Moore]

On 27 September 2015 at 11:20, Thomas Güttler
 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!! :-))
Paul
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig