Update packaging documentation

[merwok]

BPO	12779
Nosy	@birkenfeld, @pfmoore, @larryhastings, @ezio-melotti, @merwok, @sandrotosi, @sigmavirus24
Dependencies	bpo-14940: Usage documentation for pysetup

^{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: ```python assignee = 'https://github.com/merwok' closed_at = created_at = labels = ['release-blocker', 'docs'] title = 'Update packaging documentation' updated_at = user = 'https://github.com/merwok' ``` bugs.python.org fields: ```python activity = actor = 'eric.araujo' assignee = 'eric.araujo' closed = True closed_date = closer = 'eric.araujo' components = ['Documentation', 'Distutils2'] creation = creator = 'eric.araujo' dependencies = ['14940'] files = [] hgrepos = [] issue_num = 12779 keywords = [] message_count = 9.0 messages = ['142367', '142368', '143551', '143687', '147873', '148196', '161888', '163211', '181344'] nosy_count = 12.0 nosy_names = ['georg.brandl', 'paul.moore', 'larry', 'ezio.melotti', 'eric.araujo', 'cvrebert', 'sandro.tosi', 'docs@python', 'alexis', 'tshepang', 'Nebelhom', 'icordasc'] pr_nums = [] priority = 'release blocker' resolution = 'wont fix' stage = 'resolved' status = 'closed' superseder = None type = None url = 'https://bugs.python.org/issue12779' versions = ['Python 3.4'] ```

[merwok]

The documentation for packaging is outdated: it refers to setup.py instead of setup.cfg or pysetup, it talks about removed parts like compress (.Z) archives or bdist_rpm, and needs a good read-through. I have started to work on this, so I’m opening this report to prevent someone else from duplicating efforts.

[merwok]

(Replying to myself so that this report doesn’t show up in the “Issues without reply” section of the weekly email)

[merwok]

To make commit review possible, I thought I’d make two patches for this: the first would be only markup fixes and minimal updates to match the reality of the code (i.e. convert setup.py examples to setup.cfg or pysetup, remove obsolete parts, etc.) and a second one with more rephrasing and reorganization (i.e. file deletions, moving chunks of docs, etc.). I’m not finished on the first patch and the diff already contains 1026 insertions and 921 deletions.

So, as potential commit reviewers, do you think I should

• 1) go ahead with my initial plan of a huge boring commit and a more interesting commit
• 2) just make one commit
• 3) one commit per file (with boring markup changes + non-boring changes)

[ezio-melotti]

1) sounds good; 2) would be fine too if it makes your life easier; 3) doesn't seem too useful.

[merwok]

I worked on this a bit more and the current boring diff has more than 1000 deleted lines and more than 1000 added lines. After thinking about it, maybe I should not make a mega-patch with markup/boring changes first but rather fix markup as part of more consistent wording and reorganization changes. The series of changesets could look like this:

• Update and improve Doc/install (the end-user guide, a few files)
• Update and improve the commands reference in Doc/packaging
• Improve introduction material in Doc/packaging
• Fix X in Doc/library/packaging.foo
• Add missing doc for packaging.spam in Doc/library
• etc.

I think that will make more sense to review.

[merwok]

Making this a release blocker for d2 1.0a4.

[b61421bd-0746-411f-ace0-3f33fc1f4713]

I think it could be helpful to have this work at least somewhere so we can work on top of it. For instance if someone wants to do changes in the documentation, then only thing it would do now would be to cause potential merge conflicts.

I'm okay to have several commits for this, as it would allow us to work on the documentation with more than one person (theoretically at least).

Plus I really want to see those changes!

[birkenfeld]

Ping. Does this block 3.3?

[merwok]

Packaging is removed from the stdlib and distutils2 is evolving into decoupled libs/tools. Closing this effort :(