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