[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']

[ncoghlan]

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

[orsenthil]

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.

[merwok]

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.

[ncoghlan]

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).

[adamwoodbeck]

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?

[merwok]

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

[orsenthil]

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.

[merwok]

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?

[mikehoy]

• 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

[merwok]

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”.

[mikehoy]

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.