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. _______________________________________________ Distutils-SIG maillist - [email protected] https://mail.python.org/mailman/listinfo/distutils-sig
