I just noticed that access to the normal distutils docs has become difficult. They are hidden as "legacy" while a link to the packaging user guide (https://packaging.python.org/en/latest/) is prominently displayed.

The problem is that the packaging user guide is an unreadable mess of recommandations, which is both tedious and unhelpful when you want a detailed documentation of e.g. the setup() function.

I would ask to revert to the "old" distutils docs until the packaging guide becomes up to the task.

The old distutils docs are actively wrong in some areas, which is why they have been moved from their previous location.

They can't be deleted yet because they contain info that needs to be moved to either the distutils module docs, the setuptools docs, or the Python Packaging User Guide (although the latter is generally not the right place for detailed API references).

Assistance salvaging the information that still needs to be retained out of the middle of the now deprecated legacy docs would be greatly appreciated.

> The old distutils docs are actively wrong in some areas

Yet they are actively useful in others.

For reference, issue #19407 covered the PEP 453 docs updates.

I tried fixing them in place, and judged it utterly impractical to do so - moving them out of the way, but keeping them available (including via existing deep links) was the resulting compromise.

If you're prepared to help extract the needed data, great, but putting them back where they were is *not* going to happen.

Ok, can you stop closing this issue?

> I tried fixing them in place, and judged it utterly impractical to do so

Why?

> If you're prepared to help extract the needed data, great, but putting them back where they were is *not* going to happen.

Why?

No, I won't stop closing this issue, because reverting to advertising the legacy installation and distribution docs through a top level docs home page link is *never going to happen* (although I'll note again that direct links into the legacy docs have been explicitly preserved).

If you have concerns that the API reference docs for distutils and setuptools are too hard to locate from packaging.python.org, then the appropriate place to file an issue is at https://github.com/pypa/python-packaging-user-guide/issues

If you have concerns with the setuptools docs, then the place to file issues is https://bitbucket.org/pypa/setuptools/issues. pip injects setuptools into all of its setup.py invocations in order to ensure modern metadata is generated, even on older versions of Python. This is one of the reasons the legacy docs are thoroughly misleading - vanilla distutils will be used only if you run setup.py directly (without pip), and the script itself imports distutils rather than setuptools. If you *do* run setup.py that way, then many now expected features of the Python packaging ecosystem like API entry point declarations, command line wrapper generation and packaging dependency declarations won't be available, as they're setuptools features, rather than distutils ones.

If you'd like more detail on all the things that are sufficiently outdated in the legacy distribution and installation docs to make them actively misleading, then the place to ask for that information is the distutils-sig mailing list, not the CPython issue tracker.

Surely, if you think you are right, you can still wait for the discussion to happen without aggressively trying to shut it down.

Besides, you are not the docs dictator, nor the distutils maintainer. We are a community, this isn't your private territory.

> If you have concerns that the API reference docs for distutils and
> setuptools are too hard to locate from packaging.python.org

No, I'm having concerns that they are too hard to locate *from docs.python.org* (which is most people's landing point, as well). Which is why I'm opening this issue here.

Since the community has been so successful at shouting down most previous attempts at fundamental Python packaging ecosystem improvements, I am extraordinarily hostile to anything that even hints at attempting to do so again. I interpreted the proposal originally put forward in this issue as just such an attempt. Specifically, it reads to me as "ah, this link was too hard to find, despite still being the top link when searching 'python distutils', let's revert all the docs changes, so newcomers to Python can go back to being just as lost and confused as they were before PEP 453 was accepted and implemented".

The legacy docs are not better than packaging.python.org or the setuptools docs - they are actively misleading in several respects, and extracting useful information from them requires that you already be an expert in the Python packaging ecosystem so you can successfully figure out which bits you need to ignore and which bits provide relevant information not yet covered anywhere else.

However, on rereading https://docs.python.org/3/distributing/, I agree it should at least point readers directly at the package API references for both distutils and setuptools. At the moment, even the existing inline references aren't hyperlinked.

The "distutils" landing page should also point readers directly at the setuptools docs, rather than requiring an indirection via the packaging user guide.

New changeset c46953d76d4c by Nick Coghlan in branch '3.4':
Issue #22711: improve links in new distribution docs
https://hg.python.org/cpython/rev/c46953d76d4c

New changeset cbb9efd48405 by Nick Coghlan in branch 'default':
Merge issue #22711 from 3.4
https://hg.python.org/cpython/rev/cbb9efd48405

I added several previously missing hyperlinks, together with a short description of some key setuptools benefits in the distutils landing page.

Let me know if you had more than that in mind.

Le 25/10/2014 15:37, Nick Coghlan a écrit :
> 
> Since the community has been so successful at shouting down most
previous attempts at fundamental Python packaging ecosystem
improvements, I am extraordinarily hostile to anything that even hints
at attempting to do so again.

You're saying that to the guy who wanted distutils2 to stay in the stdlib.

> I added several previously missing hyperlinks,

This is good. Thank you Nick!

Also, my apologies for overreacting - I interpreted the suggestion in the worst possible light, which you definitely didn't deserve.

Actually going back and rereading the guide with the benefits of a few months distance from originally writing it made the problems you encountered *much* clearer to me - the relevant links were there on the distutils landing page, but that page itself wasn't easily reachable from the top level navigation.