classification
Title: Distribution guide should link directly to distutils & setuptools API references
Type: Stage:
Components: Documentation Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, dstufft, eric.araujo, ncoghlan, pitrou, python-dev
Priority: normal Keywords:

Created on 2014-10-23 12:57 by pitrou, last changed 2014-10-25 14:25 by ncoghlan. This issue is now closed.

Messages (12)
msg229871 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-10-23 12:57
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.
msg229877 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-10-23 15:05
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.
msg229878 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-10-23 15:06
> The old distutils docs are actively wrong in some areas

Yet they are actively useful in others.
msg229881 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-10-23 15:19
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.
msg229883 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-10-23 15:25
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?
msg229908 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-10-23 22:10
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.
msg229909 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-10-23 23:32
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.
msg229998 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-10-25 13:37
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.
msg230001 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-25 14:03
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
msg230002 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-10-25 14:05
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.
msg230003 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-10-25 14:20
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!
msg230004 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-10-25 14:25
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.
History
Date User Action Args
2014-10-25 14:25:39ncoghlansetmessages: + msg230004
2014-10-25 14:20:27pitrousetstatus: open -> closed
resolution: fixed
2014-10-25 14:20:17pitrousetstatus: pending -> open

messages: + msg230003
2014-10-25 14:05:06ncoghlansetstatus: open -> pending

messages: + msg230002
2014-10-25 14:03:30python-devsetnosy: + python-dev
messages: + msg230001
2014-10-25 13:37:11ncoghlansetmessages: + msg229998
title: "legacy" distutils docs better than packaging guide -> Distribution guide should link directly to distutils & setuptools API references
2014-10-23 23:32:21pitrousetstatus: closed -> open
resolution: rejected -> (no value)
messages: + msg229909
2014-10-23 22:10:14ncoghlansetstatus: open -> closed

messages: + msg229908
2014-10-23 15:25:18pitrousetstatus: closed -> open

messages: + msg229883
2014-10-23 15:19:13ncoghlansetstatus: open -> closed
resolution: rejected
messages: + msg229881
2014-10-23 15:06:28pitrousetstatus: closed -> open
resolution: rejected -> (no value)
messages: + msg229878
2014-10-23 15:05:30ncoghlansetstatus: open -> closed
resolution: rejected
messages: + msg229877
2014-10-23 12:57:26pitroucreate