PEP 453: update the "Installing Python Modules" documentation #63606

ncoghlan · 2013-10-26T12:44:36Z

BPO	19407
Nosy	@loewis, @birkenfeld, @ncoghlan, @larryhastings, @benjaminp, @merwok, @dstufft
Dependencies	bpo-19406: PEP 453: add the ensurepip module
Files	issue19407_packaging_docs.diff: WIP patch (new guides are placeholders)

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ncoghlan'
closed_at = <Date 2014-03-13.12:14:04.955>
created_at = <Date 2013-10-26.12:44:35.758>
labels = ['deferred-blocker', 'type-feature', 'docs']
title = 'PEP 453: update the "Installing Python Modules" documentation'
updated_at = <Date 2015-11-02.07:34:28.425>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2015-11-02.07:34:28.425>
actor = 'Jon Snoo'
assignee = 'ncoghlan'
closed = True
closed_date = <Date 2014-03-13.12:14:04.955>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2013-10-26.12:44:35.758>
creator = 'ncoghlan'
dependencies = ['19406']
files = ['34307']
hgrepos = []
issue_num = 19407
keywords = ['patch']
message_count = 23.0
messages = ['201343', '201344', '201348', '201711', '201737', '202531', '205786', '205789', '205792', '207175', '207201', '212928', '212931', '212943', '212946', '212947', '213118', '213199', '213388', '213389', '213391', '213450', '253897']
nosy_count = 10.0
nosy_names = ['loewis', 'georg.brandl', 'ncoghlan', 'larry', 'benjamin.peterson', 'eric.araujo', 'python-dev', 'dstufft', 'Marcus.Smith', 'Jon Snoo']
pr_nums = []
priority = 'deferred blocker'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19407'
versions = ['Python 3.4']

ncoghlan · 2013-10-26T12:44:36Z

Updating the "Installing Python Modules" docs in 2.7, 3.3 and default to recommend pip as the default cross-platform installer.

ncoghlan · 2013-10-26T12:45:27Z

Once bpo-19406 is implemented, this will need an additional update to indicate pip should be available by default in 3.4.

ncoghlan · 2013-10-26T12:48:48Z

bpo-19347 tracks overall PEP-453 implementation progress

ncoghlan · 2013-10-30T05:40:12Z

Marcus Smith (aka @qwcode) has made good strides this week in getting the Python Packaging User Guide to a presentable state using the current Python docs theme.

Bootstrapping: https://python-packaging-user-guide.readthedocs.org/en/latest/setup.html
Usage: https://python-packaging-user-guide.readthedocs.org/en/latest/installation.html

Accordingly, I think it makes sense to:

Arrange for a copy of this guide to be hosted somewhere on docs.python.org
Refer to that from the per-version distutils guides rather than referring directly to pip-installer.org

Thoughts?

ncoghlan · 2013-10-30T14:18:35Z

Alternative (more sensible) option - leave the packaging user guide hosted on ReadTheDocs, and if we decide to add a python.org subdomain for it later, that won't break any existing links.

ncoghlan · 2013-11-10T15:07:06Z

Larry, just a heads up that as a docs patch that isn't directly affected by the feature freeze, I likely won't get to this one until after beta 1.

We'll make sure bpo-19406 and the other functional changes are resolved, though.

ncoghlan · 2013-12-10T10:49:50Z

After reviewing the Extending & Embedding docs recently, I think a disclaimer/redirect to the tool recommendations in the Python Packaging User Guide is appropriate there as well.

Marcus also added an issue to update the distutils docs themselves: https://bitbucket.org/pypa/python-packaging-user-guide/issue/29/modernize-distutils-docs

(The user guide tracker is currently serving as a metatracker for docs issues for all the core tools)

python-dev · 2013-12-10T11:19:25Z

New changeset a9f91a38a265 by Nick Coghlan in branch '2.7':
Issue bpo-19407: add Python Packaging User Guide notes
http://hg.python.org/cpython/rev/a9f91a38a265

python-dev · 2013-12-10T11:32:39Z

New changeset 16b7536e418b by Nick Coghlan in branch '3.3':
Issue bpo-19407: add Python Packaging User Guide notes
http://hg.python.org/cpython/rev/16b7536e418b

New changeset bc21da9727ad by Nick Coghlan in branch 'default':
Issue bpo-19407: merge PPUG notes from 3.3
http://hg.python.org/cpython/rev/bc21da9727ad

loewis · 2014-01-02T16:54:54Z

I suggest that a documentation issue cannot be a release blocker. Most people read the documentation online, and will read an update once it is available.

ncoghlan · 2014-01-03T02:19:56Z

Agreed, this was set to ensure Larry followed up with a "Please explain" if
I didn't get it done in a timely manner.

I'll still try to get it done for the beta, but I still have
linux.conf.aupreparation to do, so it may slip to the first RC.

ncoghlan · 2014-03-08T12:46:00Z

After attempting to fix these docs in place, I now think that's a doomed effort. However, we can't just delete them, because they still contain details that haven't been moved to the distutils module docs or the Python Packaging User Guide yet.

So, what I'm planning to do instead is leave the existing Doc/install and Doc/distutils directories alone (including all their labels), changing the top level index page to point to new Doc/installing and Doc/distributing directories, and add a link to the old guides from the distutils docs page.

That will keep the legacy docs available, while removing all the confusing legacy cruft from the new end user facing docs (which can now just be very brief before redirecting to packaging.python.org).

ncoghlan · 2014-03-08T14:13:21Z

I like the way the attached patch has worked out - I think it's complete from a structural point of view.

The two missing pieces are to fill in the contents for the new Installing and Distributing guides, and those will be kept deliberately short, since we want to minimise the duplicating of content from the Python Packaging User Guide.

MarcusSmith · 2014-03-08T18:31:28Z

"Legacy version". nice.

btw, "http://packaging.python.org/en/latest/tutorial.html#creating-and-using-virtual-environments" will certainly end up including "pyvenv" command examples as well. currently just mentioned in a footnote.

like I mentioned on distutils-sig, I still hope to submit a patch to move critical content from the legacy pages to library/distutils.rst at some point.

also, btw, maybe you can fix this page real quick? http://www.python.org/documentation/. not sure what repo/team is managing this, but it's referencing the old HHGTP.

ncoghlan · 2014-03-08T23:37:45Z

Thanks for the feedback!

Could you lob that last one at the pythondotorg issue tracker on GitHub (
https://github.com/python/pythondotorg/issues)?

ncoghlan · 2014-03-08T23:44:33Z

And regarding moving the still-relevant content to the main distutils docs,
yeah that's still a good idea. However, that's going to take a fair bit
more work, since you'll need to evaluate the legacy content to decide what
needs preserving, and I don't know the technical details well enough to
make that call.

I figure the approach in my patch is a neat hack to move that task off the
Python 3.4 critical path, while still giving new Python 3.4 users a clean
and authoritative starting point for packaging issues :)

MarcusSmith · 2014-03-11T05:35:16Z

about the hhgtp link, logged here: python/pythondotorg#268 (and already fixed)

also, pyvenv is more prominent now in PUG as of latest changes (see pypa/packaging.python.org#35)

merwok · 2014-03-12T05:36:15Z

Left some comments for Nick on Rietveld (the ever-useful CC name selection did not let me find you, so you may have not gotten a mail).

python-dev · 2014-03-13T12:14:05Z

New changeset d22ef969cb82 by Nick Coghlan in branch 'default':
Close bpo-19407: New installation & distribution guides
http://hg.python.org/cpython/rev/d22ef969cb82

ncoghlan · 2014-03-13T12:17:17Z

Not sure how much I'll be online tomorrow or Saturday, so I went ahead and committed what I had.

The new guides definitely aren't perfect, but I think they're in acceptable shape for 3.4.0, and we can improve them in parallel with Python Packaging User Guide updates (e.g. there were some "How do I...?" questions I left unanswered because the relevant PPUG sections don't have answers yet. In particular, I completely punted on the non-PyPI distribution question for now)

python-dev · 2014-03-13T12:33:52Z

New changeset f5be4ea5b43e by Nick Coghlan in branch 'default':
Issue bpo-19407: fix link
http://hg.python.org/cpython/rev/f5be4ea5b43e

python-dev · 2014-03-13T19:43:21Z

New changeset 25dc02a2acae by Ned Deily in branch 'default':
Issue bpo-19407: Fix typos in new distribution & installation guides.
http://hg.python.org/cpython/rev/25dc02a2acae

JonSnoo · 2015-11-02T07:34:28Z

The link to the "quick recommendations section" in the Python 2.7 and 3.3 docs is broken. It appears that the PPUG has changed the path from

https://python-packaging-user-guide.readthedocs.org/en/latest/current.html

to

https://python-packaging-user-guide.readthedocs.org/en/latest/current/

Also, should the "Installing Python Modules" in Python 2.7.9 and 2.7.10 be the same as the one in Python 3.4? After all, pip is included in Python 2.7.9+, isn't it?

ncoghlan added the release-blocker label Oct 26, 2013

ncoghlan self-assigned this Oct 26, 2013

ncoghlan added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Oct 26, 2013

ncoghlan added deferred-blocker and removed release-blocker labels Nov 22, 2013

ncoghlan added release-blocker and removed deferred-blocker labels Dec 10, 2013

ncoghlan added deferred-blocker and removed release-blocker labels Jan 3, 2014

python-dev mannequin closed this as completed Mar 13, 2014

ezio-melotti transferred this issue from another repository Apr 10, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PEP 453: update the "Installing Python Modules" documentation #63606

PEP 453: update the "Installing Python Modules" documentation #63606

ncoghlan commented Oct 26, 2013

ncoghlan commented Oct 26, 2013

ncoghlan commented Oct 26, 2013

ncoghlan commented Oct 26, 2013

ncoghlan commented Oct 30, 2013

ncoghlan commented Oct 30, 2013

ncoghlan commented Nov 10, 2013

ncoghlan commented Dec 10, 2013

python-dev mannequin commented Dec 10, 2013

python-dev mannequin commented Dec 10, 2013

loewis mannequin commented Jan 2, 2014

ncoghlan commented Jan 3, 2014

ncoghlan commented Mar 8, 2014

ncoghlan commented Mar 8, 2014

MarcusSmith mannequin commented Mar 8, 2014

ncoghlan commented Mar 8, 2014

ncoghlan commented Mar 8, 2014

MarcusSmith mannequin commented Mar 11, 2014

merwok commented Mar 12, 2014

python-dev mannequin commented Mar 13, 2014

ncoghlan commented Mar 13, 2014

python-dev mannequin commented Mar 13, 2014

python-dev mannequin commented Mar 13, 2014

JonSnoo mannequin commented Nov 2, 2015

PEP 453: update the "Installing Python Modules" documentation #63606

PEP 453: update the "Installing Python Modules" documentation #63606

Comments

ncoghlan commented Oct 26, 2013

ncoghlan commented Oct 26, 2013

ncoghlan commented Oct 26, 2013

ncoghlan commented Oct 26, 2013

ncoghlan commented Oct 30, 2013

ncoghlan commented Oct 30, 2013

ncoghlan commented Nov 10, 2013

ncoghlan commented Dec 10, 2013

python-dev mannequin commented Dec 10, 2013

python-dev mannequin commented Dec 10, 2013

loewis mannequin commented Jan 2, 2014

ncoghlan commented Jan 3, 2014

ncoghlan commented Mar 8, 2014

ncoghlan commented Mar 8, 2014

MarcusSmith mannequin commented Mar 8, 2014

ncoghlan commented Mar 8, 2014

ncoghlan commented Mar 8, 2014

MarcusSmith mannequin commented Mar 11, 2014

merwok commented Mar 12, 2014

python-dev mannequin commented Mar 13, 2014

ncoghlan commented Mar 13, 2014

python-dev mannequin commented Mar 13, 2014

python-dev mannequin commented Mar 13, 2014

JonSnoo mannequin commented Nov 2, 2015