Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

move the "Uploading Packages" section to distutils/packageindex.rst #60610

Closed
cjerdonek opened this issue Nov 4, 2012 · 12 comments
Closed

move the "Uploading Packages" section to distutils/packageindex.rst #60610

cjerdonek opened this issue Nov 4, 2012 · 12 comments
Assignees
@merwok
Labels
docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir type-feature A feature request or enhancement

Comments

@cjerdonek
Copy link
Member

BPO 16406
Nosy @birkenfeld, @tarekziade, @ezio-melotti, @merwok, @cjerdonek
Files
  • issue-16406-1.patch
  • issue-16406-2.patch
  • issue-16406-3.patch
  • issue-16406-4.patch
    		•

    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/merwok'
closed_at = <Date 2013-02-27.18:07:37.497>
created_at = <Date 2012-11-04.19:03:12.967>
labels = ['easy', 'type-feature', 'library', 'docs']
title = 'move the "Uploading Packages" section to distutils/packageindex.rst'
updated_at = <Date 2013-02-27.18:17:08.156>
user = 'https://github.com/cjerdonek'

    bugs.python.org fields:

    activity = <Date 2013-02-27.18:17:08.156>
actor = 'chris.jerdonek'
assignee = 'eric.araujo'
closed = True
closed_date = <Date 2013-02-27.18:07:37.497>
closer = 'chris.jerdonek'
components = ['Distutils', 'Documentation']
creation = <Date 2012-11-04.19:03:12.967>
creator = 'chris.jerdonek'
dependencies = []
files = ['28663', '28665', '28710', '29227']
hgrepos = []
issue_num = 16406
keywords = ['patch', 'easy']
message_count = 12.0
messages = ['174825', '177189', '177190', '177204', '179510', '179526', '179844', '182914', '183164', '183167', '183168', '183170']
nosy_count = 6.0
nosy_names = ['georg.brandl', 'tarek', 'ezio.melotti', 'eric.araujo', 'chris.jerdonek', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue16406'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3', 'Python 3.4']
    @cjerdonek
    Copy link
    Member Author

    I think the Package Index (PyPI) documentation would be clearer if the section called "Uploading Packages to the Package Index":

    http://docs.python.org/3.4/distutils/uploading.html

    were made a part of the previous section about PyPI (now called "Registering with the Package Index"):

    http://docs.python.org/3.4/distutils/packageindex.html

    The combined section could then be renamed simply to "The Python Package Index (PyPI)".

    Both sections are small and very closely related. For example, the second half of the section on uploading (the subsection called "PyPI package display") is not actually about uploading but rather about registering and PyPI in general. Similarly, the second half of the first section on registering (the subsection called "The .pypirc file") applies equally to uploading as it does to registering.

    I was affected by the current organization, for example, because it gave the impression that uploading updates the PyPI package display (which is conceivable since PKG-INFO is part of the uploaded files). Rather, it is registering a version which updates the package display for that version.

    A combined section on PyPI would better reflect how things should be understood.

    @cjerdonek cjerdonek added stdlib Python modules in the Lib dir docs Documentation in the Doc dir easy type-feature A feature request or enhancement labels Nov 4, 2012
    @merwok
    Copy link
    Member

    merwok commented Dec 9, 2012

    I’m reluctant to break links. I think the issues you report could be fixed or mitigated with changes to text, clarifications, interlinks. What do you think?

    @cjerdonek
    Copy link
    Member Author

    I've been meaning to ask Georg or anyone else knowledgeable about what options we have for redirects, etc. -- specifically for this issue. Maybe something similar can even be done using Sphinx.

    If we can't redirect, I was thinking even a stub page with a manual link to the PyPI page might be an improvement (to prevent the broken external link issue you mention).

    @birkenfeld
    Copy link
    Member

    Redirects are no problem in principle, but it should not get out of hand. A simple "this was here but now isn't" page might be better.

    @cjerdonek
    Copy link
    Member Author

    Attached is a proposed patch.

    @cjerdonek
    Copy link
    Member Author

    Updating patch with use of the :orphan: directive (so that the old page can be excluded from the table of contents/toctree without issuing a Sphinx warning).

    @cjerdonek
    Copy link
    Member Author

    Updated the last patch by moving the "PyPI package display" to beneath the "Registering Packages" section (since only the register command affects the package display).

    Éric, does this look okay to you? I didn't change the text of any of the sections -- only moved them (and added introductory page text and index entries).

    @cjerdonek
    Copy link
    Member Author

    Attaching an improved patch.

    This patch improves the introductory wording, adds some additional hyperlinks, and changes the order of one of the inserted sections.

    @merwok
    Copy link
    Member

    merwok commented Feb 27, 2013

    LGTM. Some comments on Rietveld.

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Feb 27, 2013

    New changeset a9565750930e by Chris Jerdonek in branch '2.7':
    Issue bpo-16406: combine the doc pages for uploading and registering to PyPI.
    http://hg.python.org/cpython/rev/a9565750930e

    New changeset f57ddf3c3e5d by Chris Jerdonek in branch '3.2':
    Issue bpo-16406: Combine the doc pages for uploading and registering to PyPI.
    http://hg.python.org/cpython/rev/f57ddf3c3e5d

    New changeset 58a28aa70fec by Chris Jerdonek in branch '3.3':
    Issue bpo-16406: Combine the doc pages for uploading and registering to PyPI.
    http://hg.python.org/cpython/rev/58a28aa70fec

    New changeset 44ebac378e51 by Chris Jerdonek in branch 'default':
    Issue bpo-16406: Combine the doc pages for uploading and registering to PyPI.
    http://hg.python.org/cpython/rev/44ebac378e51

    @cjerdonek
    Copy link
    Member Author

    Thanks a lot for taking the time to review, guys.

    @cjerdonek
    Copy link
    Member Author

    I created bpo-17311 for a suggestion Éric made on Rietveld.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees

    @merwok merwok

    Labels
    docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @birkenfeld @cjerdonek @merwok