just use a readme, not a description and readme file about sampleproject HOT 7 CLOSED

+1 to this change. I think this is a case of the sample project over-thinking things instead of just paving the cowpaths that are actually used. I've seen hundreds of projects that parse their README file into long_description; I can only recall ever seeing one project ever parse some other file (it was older versions of pip itself, parsed part of doc/index.rst instead).

Sure it's possible that in some odd situations you might want your project page on PyPI to have different content from your project description on GitHub/Bitbucket/etc, but empirical evidence strongly suggests that that's not the common case for most projects. The sample project should default to the simpler option that matches what makes sense for most new projects.

from sampleproject.

(Also, a rule that might be worth considering -- if the PyPA's own projects don't follow the sample project, there should be a good reason why they are special and unlike most projects. In this case, pip itself parses README.rst for its long-description, and there is no reason why it is special in that regard.)

from sampleproject.

FTR there are a great deal of projects that use text other than README.* for their long_description.

flask, virtualenv, setuptools, sopel, numpy, scipy to name some popular ones.

I can very easily see one wanting to distinguish what's on PyPI's page for a project, from the project's general readme, although certainly not always. A project might not be python-only and have it's README written in markdown, for only one sensible reason.

from sampleproject.

@Ivoz I've seen quite a few projects that embed their long-description text directly into setup.py (like Flask and numpy/scipy do); that doesn't fit the description "parse some other file." I don't think direct-embedding is the approach sampleproject should recommend, but if you want to advocate for it, go ahead.

Virtualenv does the same thing pip used to (parse docs/index.rst), as I mentioned above, probably just because nobody has ever bothered to update it. I haven't seen other projects picking up on that approach.

I've never seen a project use a dedicated file (with no other use) for long-description, like sampleproject did before my PR was merged. I'm sure there may be one or two out there, but it's certainly not a common practice.

from sampleproject.

I just don't think there is one true, always-objectively-best method here, just as there is no one, true always-objectively-best method to splitting up code into module and packages.

They don't fit the description "parse some other file", but they do fit the description "don't get your long_description directly from your README". I see "use a DESCRIPTION.rst" as just the simplest implementation of that.

Pip & virtualenv specifically keep their README limited to mostly just a link to the documentation in order that the README always refers to the most up to date, correct information about the project (the docs) - rather than haphazardly falling behind when it's not updated in a while. Not because no-one has bothered to update it.

I guess I just want to argue the point that a README and long_description are sometimes, but definitely not always, synonymous texts. I don't think there's an objective preference to be had.

from sampleproject.

I agree that there is not one always-objectively-best-for-all-projects option here. Same will be true for most choices sampleproject has to make.

I do think there is a clear "simplest, very commonly used, and good enough for almost all new/small projects" option here, and in general I think that's the option sampleproject should go for with this type of choice.

from sampleproject.

I don't think a sample project should deviate from the most common patterns without something that is objectively better.

from sampleproject.