<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Mar 30, 2015 at 11:14 AM, Daniel Holth <span dir="ltr"><<a href="mailto:dholth@gmail.com" target="_blank">dholth@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div class=""><div class="h5">On Mon, Mar 30, 2015 at 11:55 AM, Ian Cordasco<br>
<<a href="mailto:graffatcolmingov@gmail.com">graffatcolmingov@gmail.com</a>> wrote:<br>
><br>
><br>
> On Mon, Mar 30, 2015 at 10:47 AM, Ionel Cristian Mărieș <<a href="mailto:contact@ionelmc.ro">contact@ionelmc.ro</a>><br>
> wrote:<br>
>><br>
>> On Mon, Mar 30, 2015 at 6:39 PM, Xavier Fernandez<br>
>> <<a href="mailto:xav.fernandez@gmail.com">xav.fernandez@gmail.com</a>> wrote:<br>
>>><br>
>>> I think the point was not to say that documentation is useless (and there<br>
>>> is some: <a href="http://flit.readthedocs.org/en/latest/" target="_blank">http://flit.readthedocs.org/en/latest/</a> ) but that the<br>
>>> code/implementation is much simpler than the combination of<br>
>>> distutils/setuptools/bdist_wheel.<br>
>>><br>
>>> On Mon, Mar 30, 2015 at 5:26 PM, Ian Cordasco<br>
>>> <<a href="mailto:graffatcolmingov@gmail.com">graffatcolmingov@gmail.com</a>> wrote:<br>
>>>><br>
>>>><br>
>>>> So for new python programmers (or newbie users in general) reading the<br>
>>>> entire source of another package to understand it is a better experience?<br>
>>>><br>
>> To put that in context, flit goes for less than 600 SLOC while<br>
>> distutils+setuptools+wheel amount to over 20000 SLOC. At that ratio<br>
>> arguments for distutils+setuptools+wheel documentation seem unreasonable.<br>
><br>
><br>
> To be clear, no one should ever be advocating to "just read the source" as a<br>
> form of documentation. This is why the Packaging guide exists (because no<br>
> one should ever be expected to read the distutils, setuptools, or wheel<br>
> source to use it).<br>
><br>
> Code is never as self-documenting as people like to believe. And since we're<br>
> talking about new users (without defining what they're new to) reading the<br>
> source should only be for educational purposes. cookiecutter will serve new<br>
> users better than flit or anything else. cookiecutter will teach new users<br>
> good package structure and take care of the (possibly hard parts) of a<br>
> setup.py. Then, when the "new user" goes to publish it, there's tons of<br>
> prior documentation on how to do it. If they run into problems using flit<br>
> they have the skimpy documentation or the source.<br>
><br>
> Yeah, it's "easy" to read 600 SLOC for you, but what about for some "new<br>
> user"? Are they new to python? Why do they have to care about reading the<br>
> source if something else will "just work" as documented for their "simple"<br>
> use case?<br>
<br>
</div></div>No one has advocated reading the source code instead of reading the<br>
documentation.<br></div></blockquote><div><br></div><div>Thankfully this is a publicly archived list. Quoting yourself:<br><br>> Flit is one example, and you can understand
it not by copy/pasting,<br>> but by spending half an hour reading its
complete source code.<br><br></div><div>In which you advocate reading the source of a tool over using setup.py which has countless resources written about it on the internet.<br></div></div></div></div>