On Mon, Mar 30, 2015 at 11:14 AM, Daniel Holth <dholth@gmail.com> wrote:
On Mon, Mar 30, 2015 at 11:55 AM, Ian Cordasco <graffatcolmingov@gmail.com> wrote:
On Mon, Mar 30, 2015 at 10:47 AM, Ionel Cristian Mărieș <
wrote:
On Mon, Mar 30, 2015 at 6:39 PM, Xavier Fernandez <xav.fernandez@gmail.com> wrote:
I think the point was not to say that documentation is useless (and
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@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
contact@ionelmc.ro> there 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.