On 2 Apr 2014 06:41, "Paul Moore" <p.f.moore@gmail.com> wrote:
>
> On 1 April 2014 21:16, Michael Merickel <mmericke@gmail.com> wrote:
> > Yeah, setuptools is a bw-compat wrapper around distutils, so it tends to
> > only document its new features. This approach to documentation makes it very
> > difficult to understand for newcomers that are not familiar with distutils.
> > Especially now that setuptools is the de facto standard that everyone is
> > learning how to use.
>
> Agreed. The packaging documentation grew piecemeal over time, staring
> from a basis of the distutils documentation which was itself pretty
> incomprehensible. We're working on a new iteration of the packaging
> documentation at
> https://python-packaging-user-guide.readthedocs.org/en/latest/ but to
> be honest, it's very easy to take for granted a lot of basics, simply
> because the people doing the writing are too close to the packaging
> ecosystem.

Marcus has also been doing a lot of work trying to coordinate consistency updates to the stdlib, pip, virtualenv and setuptools docs to get them in sync with each other and bring them into line with the new overall user guide (Now available as packaging.python.org, btw).

The fact several aspects of the setuptools docs assume readers are already experienced distutils users just happens to be one of the harder problems to resolve in that space, as fixing it requires extracting the relevant info from the 15+ year old distutils docs and combining it with the already complicated setuptools docs :P

(It's also influenced by the fact that more of the PyPA's focus for the past year has been on cleaning up the installation side of the story. As that has now reached a better state with the release of Python 3.4 and its bundled pip bootstrapping mechanism, I expect we'll see more movement on the build side of things this year)

Cheers,
Nick.

>For example, I don't think anyone considered documenting a
> single Python module as mentioned by the OP (it's usually the case
> that your needs very soon grow to the point where a single module
> isn't enough, but that's not a reason to not cover it - just a
> possible reason why we never thought of it).
>
> We'd be very grateful for any contributions to the packaging user
> guide, either in the form of pull requests or even just issues on the
> tracker pointing at things we should cover (or should cover better).
>
> Paul
> _______________________________________________
> Distutils-SIG maillist  -  Distutils-SIG@python.org
> https://mail.python.org/mailman/listinfo/distutils-sig