[Distutils] it's happened - wheels without sdists (flit)

[Daniel Holth]

On Mon, Mar 30, 2015 at 11:55 AM, Ian Cordasco
<graffatcolmingov at gmail.com> wrote:
>
>
> On Mon, Mar 30, 2015 at 10:47 AM, Ionel Cristian Mărieș <contact at ionelmc.ro>
> wrote:
>>
>> On Mon, Mar 30, 2015 at 6:39 PM, Xavier Fernandez
>> <xav.fernandez at gmail.com> wrote:
>>>
>>> I think the point was not to say that documentation is useless (and there
>>> is some: http://flit.readthedocs.org/en/latest/ ) but that the
>>> code/implementation is much simpler than the combination of
>>> distutils/setuptools/bdist_wheel.
>>>
>>> On Mon, Mar 30, 2015 at 5:26 PM, Ian Cordasco
>>> <graffatcolmingov at gmail.com> wrote:
>>>>
>>>>
>>>> So for new python programmers (or newbie users in general) reading the
>>>> entire source of another package to understand it is a better experience?
>>>>
>> To put that in context, flit goes for less than 600 SLOC while
>> distutils+setuptools+wheel amount to over 20000 SLOC. At that ratio
>> arguments for distutils+setuptools+wheel documentation seem unreasonable.
>
>
> To be clear, no one should ever be advocating to "just read the source" as a
> form of documentation. This is why the Packaging guide exists (because no
> one should ever be expected to read the distutils, setuptools, or wheel
> source to use it).
>
> Code is never as self-documenting as people like to believe. And since we're
> talking about new users (without defining what they're new to) reading the
> source should only be for educational purposes. cookiecutter will serve new
> users better than flit or anything else. cookiecutter will teach new users
> good package structure and take care of the (possibly hard parts) of a
> setup.py. Then, when the "new user" goes to publish it, there's tons of
> prior documentation on how to do it. If they run into problems using flit
> they have the skimpy documentation or the source.
>
> Yeah, it's "easy" to read 600 SLOC for you, but what about for some "new
> user"? Are they new to python? Why do they have to care about reading the
> source if something else will "just work" as documented for their "simple"
> use case?

No one has advocated reading the source code instead of reading the
documentation.