On Mon, Mar 30, 2015 at 11:14 AM, Daniel Holth <[email protected]> wrote:
> On Mon, Mar 30, 2015 at 11:55 AM, Ian Cordasco > <[email protected]> wrote: > > > > > > On Mon, Mar 30, 2015 at 10:47 AM, Ionel Cristian Mărieș < > [email protected]> > > wrote: > >> > >> On Mon, Mar 30, 2015 at 6:39 PM, Xavier Fernandez > >> <[email protected]> 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 > >>> <[email protected]> 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. > Thankfully this is a publicly archived list. Quoting yourself: > Flit is one example, and you can understand it not by copy/pasting, > but by spending half an hour reading its complete source code. In which you advocate reading the source of a tool over using setup.py which has countless resources written about it on the internet.
_______________________________________________ Distutils-SIG maillist - [email protected] https://mail.python.org/mailman/listinfo/distutils-sig
