Write 'Using Python on Platform X' documents

[1a90d5ba-e091-4ed6-a644-41c5568983da]

BPO	469773
Nosy	@freddrake, @akuchling, @birkenfeld

^{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/birkenfeld' closed_at = created_at = labels = ['type-feature', 'docs'] title = "Write 'Using Python on Platform X' documents" updated_at = user = 'https://bugs.python.org/anthonybaxter' ``` bugs.python.org fields: ```python activity = actor = 'georg.brandl' assignee = 'georg.brandl' closed = True closed_date = closer = 'georg.brandl' components = ['Documentation'] creation = creator = 'anthonybaxter' dependencies = [] files = [] hgrepos = [] issue_num = 469773 keywords = [] message_count = 9.0 messages = ['6885', '6886', '6887', '6888', '6889', '6890', '55186', '57982', '58199'] nosy_count = 4.0 nosy_names = ['fdrake', 'akuchling', 'anthonybaxter', 'georg.brandl'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'closed' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue469773' versions = [] ```

[1a90d5ba-e091-4ed6-a644-41c5568983da]

Some stuff that's in the man page (e.g. the syntax for the -W switch) doesn't appear to be in the HTML documentation. If it is there, it's _very_ well hidden away.

[freddrake]

Logged In: YES user_id=3066

I agree.

Where would you suggest the information be added?

[1a90d5ba-e091-4ed6-a644-41c5568983da]

Logged In: YES user_id=29957

See, that's the problem :) It's not clear where this might go - it's almost a "Using Python" section, which, as far as I can see, doesn't really exist.

This might also include stuff about the Windows GUI and other interfaces for using python.

If a shorter-term "just get the -W stuff in" approach is wanted, then extended the lib/module-warnings might be the approach... but it really does seem like it needs to be somewhere central.

[freddrake]

Logged In: YES user_id=3066

I'll note that the "Macintosh Library Modules" document deals with this sort of issue for the Mac (though it may be out of date for Mac OS X; not sure). The first chapter is an introduction to using Python on the Mac, and the remaining chapters provide module reference documentation.

What's needed is something like the first chapter of that for Unix and Windows. I'm not sure where it should go, though; I don't want that material in the main library reference.

This almost makes me want three platform-specific documents, one for Windows, one for Unix, and the existing Mac OS document, each containing the relevant "Using Python on ..." chapter, followed by chapters containing platform-specific modules. Modules that apply to two or more of the platforms would continue to be documented in the main library reference. The distutils modules are already documented in the distutils documentation as well. This should be fine since the "global" module index is the normal general entry point anyway.

[1a90d5ba-e091-4ed6-a644-41c5568983da]

Logged In: YES user_id=29957

What about instead a new "Using Python" document. There's a bunch of overlap between the platforms. We can then also have separate chapters for Mac, Win, Unix. I think trying to produce platform specific docs is going to be a headache in the long run.

[akuchling]

Changing summary to be more accurate.

[birkenfeld]

See bpo-223599 (which I closed as duplicate of this) for a few specific Windows questions.

[birkenfeld]

This will hopefully be done in GHOP.

[birkenfeld]

Okay, now we have documents for Unix, Windows and Mac!