[doc] Missing items in installation/setup instructions

@ncoghlan

BPO	12436
Nosy	@ncoghlan, @orsenthil, @pitrou, @vstinner, @ezio-melotti, @merwok
Files	issue12436-notepad_plus_plus.diff issue12436-notepad_plus_plus_2.diff issue12436-notepad_plus_plus_3.diff

^{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 = None
created_at = <Date 2011-06-28.23:56:34.743>
labels = ['3.8', '3.9', '3.10', 'docs']
title = '[doc] Missing items in installation/setup instructions'
updated_at = <Date 2020-11-06.20:05:29.977>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2020-11-06.20:05:29.977>
actor = 'iritkatriel'
assignee = 'eric.araujo'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2011-06-28.23:56:34.743>
creator = 'ncoghlan'
dependencies = []
files = ['26891', '26902', '26904']
hgrepos = []
issue_num = 12436
keywords = ['patch']
message_count = 25.0
messages = ['139381', '139719', '140141', '140175', '140881', '140885', '141456', '141509', '145049', '145094', '145106', '145114', '145121', '145132', '145134', '145135', '145207', '145265', '145286', '145306', '168128', '168343', '168548', '168604', '348651']
nosy_count = 10.0
nosy_names = ['ncoghlan', 'orsenthil', 'pitrou', 'vstinner', 'ezio.melotti', 'eric.araujo', 'docs@python', 'tshepang', 'adam.woodbeck', 'mikehoy']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue12436'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

The Boston Python Workshop folks have some detailed step-by-step instructions on getting Python up and running ([1]).

Given that this can be a pain point for new users (primarily on Windows), it may be good to reference these instructions from the official docs. (Alternatively, we could use them as the basis for a "HOWTO" in the official docs and update release.py to adjust the relevant links. That's a lot more work than just adding a link, though)

[1] http://openhatch.org/wiki/Boston_Python_Workshop_3/Friday

I am not sure that is comprehensive enough. It is just organized into
OS specific sections and gives little details further on.
So, -1 to this, but +1 to the general idea of having detailed install
and get started documentation.

Goal #1: set up Python

I believe http://docs.python.org/dev/using/ covers this.

Goal #2: prepare a text editor

This is missing from our docs. (My first thought was that it was out of scope, but for complete beginners, it would be nice to give a few pointers.)

Goal #3: practice starting and exiting Python

The tutorial has one page about that.

Goal #4: practice navigating the computer from a command prompt

Out of scope?

Goal #5: practice running Python code from a file

This is probably in the tutorial or using docs, I have to check.

Goal #6: get dependencies installed for the Saturday projects

This used to be non-standard, but now that we have packaging and pysetup, I translate this item to a doc bug: Explain how to use pysetup to get dependencies (in using, I think).

Goal #7: start learning Python!
Goal #8: Checkoff

Nothing to add, IMO.

Nice, I didn't know we have those comprehensive using docs. However, they should be linked from http://docs.python.org/dev/tutorial/interpreter.html (definitely inline and perhaps a see also).

So what we're looking for is comprehensive HOWTOs for installing and running Python on Windows, OSX and Linux to be added to http://docs.python.org/howto/index.html?

IMO we don’t need HOWTOs that duplicate existing docs, but we may need additions to the existing tutorial and “using” docs. See http://bugs.python.org/issue12436#msg140141

I propose we close this, because it adds a little value as a separate bug. If there are specific sections in the docs that can be improved, we can deal with that.

I propose that we just narrow the scope of this report. If you agree with my earlier message, the current docs just need a few patches:

How to prepare a text editor
How to run Python code from a file (if the tutorial or using docs don’t already have it).

It would also be nice to have feedback from beginners about our tutorial and using docs: Are they comprehensive and easy to find?

How to prepare a text editor
See: http://docs.python.org/dev/using/unix.html#editors

How to run Python code from a file (if the tutorial or using docs don’t already have it).

See: http://docs.python.org/dev/using/unix.html#miscellaneous

Thanks Mike! So the first item is covered (at least for UNIX, can you check the Windows docs too?), but not the second. The item you linked to explains how to modify a script so that it’s possible to run ./script on Unix, but does not give an actual example of running it, nor does it explain “python script” or “python script.py” or “python -m module”.

Thanks Mike! So the first item is covered (at least for UNIX, can you
check the Windows docs too?), but not the second.

http://docs.python.org/dev/using/windows.html Makes no reference to preparing a text editor. This I could help with but...

The item you linked
to explains how to modify a script so that it’s possible to run
./script on Unix, but does not give an actual example of running it,
nor does it explain “python script” or “python script.py” or “python -m
module”.

Some one else would have to write this part unless you can give me some info about how it should be worded.

Thanks, I will take all contributions and suggestions and propose one patch.

I am able to start working on this issue again, Eric. If you want to give me the status of your patch I can either help you finish it up or I can make one this week.

My computer currently doesn’t boot so I can’t check if I had started or not. You can propose a patch incorporating the various suggestions, or give me some days to read this again and make a summary of what I would have done. Thanks!

Here is a patch for just Notepad++.

Wrapped my text columns to 80. Ignore v2.

This issue is not newcomer friendly, I remove the easy keyword.

This issue is stale, is there any interest in pursuing it?

Navigation Menu

Repository navigation

[doc] Missing items in installation/setup instructions #56645

11 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

[doc] Missing items in installation/setup instructions #56645

Description

Activity

ncoghlan commented on Jun 28, 2011

orsenthil commented on Jul 4, 2011

merwok commented on Jul 11, 2011

ncoghlan commented on Jul 12, 2011

adamwoodbeck commented on Jul 22, 2011

merwok commented on Jul 22, 2011

orsenthil commented on Jul 31, 2011

merwok commented on Aug 1, 2011

mikehoy commented on Oct 6, 2011

merwok commented on Oct 7, 2011

mikehoy commented on Oct 7, 2011

11 remaining items

mikehoy commented on Aug 13, 2012

merwok commented on Aug 15, 2012

mikehoy commented on Aug 19, 2012

mikehoy commented on Aug 19, 2012

vstinner commented on Jul 29, 2019

devdanzin commented on Sep 18, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions