README.rst vs DESCRIPTION.rst
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/
On 27 September 2015 at 11:20, Thomas Güttler <guettliml@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!! :-)) Paul
Am 27.09.2015 um 13:06 schrieb Paul Moore:
On 27 September 2015 at 11:20, Thomas Güttler <guettliml@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? Regards, Thomas Güttler -- http://www.thomas-guettler.de/
On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler < guettliml@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
On Sun, Sep 27, 2015 at 1:18 PM, Ionel Cristian Mărieș <contact@ionelmc.ro> wrote:
On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler <guettliml@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.
On Mon, Sep 28, 2015 at 12:20 AM, Ian Cordasco <graffatcolmingov@gmail.com> 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
On Sun, Sep 27, 2015 at 4:55 PM, Ionel Cristian Mărieș <contact@ionelmc.ro> wrote:
On Mon, Sep 28, 2015 at 12:20 AM, Ian Cordasco <graffatcolmingov@gmail.com> 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.
Sent from my iPhone On Sep 27, 2015, at 11:19 AM, Ionel Cristian Mărieș <contact@ionelmc.ro> wrote: On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler <guettliml@thomas-guettler. <guettliml@thomas-guettler.de> 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
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.barker@noaa.gov> wrote:
Sent from my iPhone
On Sep 27, 2015, at 11:19 AM, Ionel Cristian Mărieș <contact@ionelmc.ro> wrote:
On Sun, Sep 27, 2015 at 8:05 PM, Thomas Güttler < guettliml@thomas-guettler. <guettliml@thomas-guettler.de> 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
On 27 September 2015 at 18:05, Thomas Güttler <guettliml@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
What it is `long_description` is generally, most applicably, what gets put on the project's pypi page. Sometimes this is exactly the same thing as what you want on your project's general "read me" text, sometimes not. For example, the two are different for flask, virtualenv, setuptools, sopel, numpy But as for django there are also many examples where the two are the same - pip, tornado, etc, etc. I have trouble finding an objective reasoning that one method is to be objectively preferred over the other. I think it can vary a lot given the size and scale of the project, its nature, application vs library, etc. Sometimes someone might prefer their README as a plain txt file, or maybe in markdown. However a `long_description` is always parsed as rst, at least for the present. So there is at least one possible reason. It's possible maybe the text in DESCRIPTION.rst could be changed to indicate the possibilities better. We always want to balance this with keeping `sampleproject` as simple as possible to make it practical and immediately useful, rather than overly technical. Cheers, Matt Matt Iversen // matt at notevencode.com PGP: 0xc046e8a874522973 // 2F04 3DCC D6E6 D5AC D262 2E0B C046 E8A8 7452 2973 On 27/09/2015 8:20 PM, Thomas Güttler wrote:
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
On Mon, Sep 28, 2015 at 11:19 AM, Matthew Iversen <matt@notevencode.com> 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&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
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/e7de7861963274595c5b3b0d6942e35... 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
participants (8)
-
Chris Barker -
Chris Barker - NOAA Federal
-
Ian Cordasco -
Ionel Cristian Mărieș -
Marcus Smith -
Matthew Iversen -
Paul Moore -
Thomas Güttler