classification
Title: Missing items in installation/setup instructions
Type: Stage:
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: adam.woodbeck, docs@python, eric.araujo, ezio.melotti, mikehoy, ncoghlan, orsenthil, pitrou, tshepang
Priority: normal Keywords: easy, patch

Created on 2011-06-28 23:56 by ncoghlan, last changed 2012-08-19 22:53 by mikehoy.

Files
File name Uploaded Description Edit
issue12436-notepad_plus_plus.diff mikehoy, 2012-08-19 07:22 review
issue12436-notepad_plus_plus_2.diff mikehoy, 2012-08-19 22:33 review
issue12436-notepad_plus_plus_3.diff mikehoy, 2012-08-19 22:53 review
Messages (24)
msg139381 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-06-28 23:56
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
msg139719 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-07-04 00:19
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.
msg140141 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-11 16:13
> 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.
msg140175 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-07-12 07:15
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).
msg140881 - (view) Author: Adam Woodbeck (adam.woodbeck) * Date: 2011-07-22 14:22
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?
msg140885 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-22 15:09
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
msg141456 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-07-31 02:59
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.
msg141509 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-08-01 13:33
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?
msg145049 - (view) Author: Mike Hoy (mikehoy) * Date: 2011-10-06 22:59
> - 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
msg145094 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-07 16:13
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”.
msg145106 - (view) Author: Mike Hoy (mikehoy) * Date: 2011-10-07 17:10
> 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.
msg145114 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-07 17:38
> http://docs.python.org/dev/using/windows.html Makes no reference to
> preparing a text editor. This I could help with but...
Cool, please follow the guidelines in the devguide to make a patch for 3.2.  It should be something short, like the unix docs, mostly to recommend Notepad++ I think.

For Windows users, added a section about how to use a terminal and possibly a link to PowerShell would be another good addition IMO.

> Some one else would have to write this part unless you can give me
> some info about how it should be worded.
I’ll propose a patch.
msg145121 - (view) Author: Mike Hoy (mikehoy) * Date: 2011-10-07 18:30
> mostly to recommend Notepad++ I think.

In addition to Notepad++ do you think it would be a good idea to at least mention Vim and Emacs with a disclaimer about the learning curve?

> For Windows users, added a section about how to use a terminal and 

Do you think it would be a good idea to add instructions on how to add Python to the Path in Windows? It could be 'borrowed' from the Boston Python Workshop Page I would think. It's pretty long but useful considering how much trouble I have had having to do this myself under Windows.
msg145132 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-07 19:30
> In addition to Notepad++ do you think it would be a good idea to at
> least mention Vim and Emacs with a disclaimer about the learning curve?

I'm not sure how many windows user use Vim/Emacs.  Maybe PyScripter could be mentioned too, but I'm not sure how popular it is and if there are better alternatives.

> Do you think it would be a good idea to add instructions on how to add
> Python to the Path in Windows? 

Yes, but isn't there a script somewhere that does that already?
msg145134 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-10-07 19:37
> In addition to Notepad++ do you think it would be a good idea to at
> least mention Vim and Emacs with a disclaimer about the learning curve?

I'm a bit surprised. I would think the devguide is aimed are people who are *already* programmers, and have chosen their tools. Therefore I don't know how such material is useful, and the devguide is already hefty enough.
msg145135 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-10-07 19:38
Oops. I just noticed this issue is not talking about the devguide, but the general docs. Please ignore the message above.
msg145207 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-09 03:19
> In addition to Notepad++ do you think it would be a good idea to at
> least mention Vim and Emacs with a disclaimer about the learning
> curve?
No.  If someone is looking at this page and doesn’t already have a text editor they’re familiar with, I think Notepad++ is the right tool to suggest.

> Do you think it would be a good idea to add instructions on how to add Python
> to the Path in Windows?
The doc already has that somewhere, unless I misremember.

> Yes, but isn't there a script somewhere that does that already?
One or more in Tools/scripts and maybe in PC or PCbuild too.
msg145265 - (view) Author: Mike Hoy (mikehoy) * Date: 2011-10-09 15:43
Here is what I have so far:

> For Windows users, added a section about how to use a terminal

How to use a terminal

Open a command prompt:

* On Windows Vista or Windows 7: click on the Start menu (the Windows logo in the lower left of the screen), type cmd into the Search field directly above the Start menu button, and click on "cmd" in the search results above the Search field.

* On Windows XP: click on the Start menu (the Windows logo in the lower left of the screen), click on "Run...", type cmd into the text box, and hit enter.

Commands used in terminal

* cd C:\ - Puts you in the root directory of the C drive.
* cd Python32 - Puts you in the directory where Python 3.2 is installed.
* dir - This command lists the contents of the Python32 directory.
* python - This command will invoke python.exe and bring up the interpreter.

> a link to PowerShell 

Windows PowerShell

Windows PowerShell is a task-based command-line shell and scripting language designed for system administration. It can be obtained here: http://technet.microsoft.com/en-us/library/bb978526.aspx.
msg145286 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-09 22:57
> Open a command prompt:
Another alternative is win+r -> type 'cmd' -> hit enter.  This should work on all the Windows versions.

> * cd C:\ - Puts you in the root directory of the C drive.
> * cd Python32 - Puts you in the directory where Python 3.2 is installed.

What if it's not installed there?  Maybe it's better to say something like "use the 'cd' command to move to the directory where Python is installed" possibly mentioning the default installation directory and  'cd ..'.

> * dir - This command lists the contents of the Python32 directory.
> * python - This command will invoke python.exe and bring up the 
interpreter.

If the dir is already added to the PATH 'python' will work already without having to navigate to the installation dir.
Also if the user installed Python there should be a "Python (command line)" entry in the start menu that brings up the interpreter.
msg145306 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-10 15:42
Thanks, I will take all contributions and suggestions and propose one patch.
msg168128 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-13 17:05
>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.
msg168343 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-08-15 22:52
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!
msg168548 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-19 07:22
Here is a patch for just Notepad++.
msg168604 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-19 22:53
Wrapped my text columns to 80. Ignore v2.
History
Date User Action Args
2012-08-19 22:53:25mikehoysetfiles: + issue12436-notepad_plus_plus_3.diff

messages: + msg168604
2012-08-19 22:33:25mikehoysetfiles: + issue12436-notepad_plus_plus_2.diff
2012-08-19 07:22:51mikehoysetfiles: + issue12436-notepad_plus_plus.diff
keywords: + patch
messages: + msg168548
2012-08-15 22:52:24eric.araujosetmessages: + msg168343
2012-08-13 17:05:13mikehoysetmessages: + msg168128
2012-04-15 00:18:43tshepangsetnosy: + tshepang
2011-10-10 15:42:57eric.araujosetassignee: docs@python -> eric.araujo
messages: + msg145306
2011-10-09 22:57:59ezio.melottisetmessages: + msg145286
2011-10-09 15:43:50mikehoysetmessages: + msg145265
2011-10-09 03:19:52eric.araujosetmessages: + msg145207
2011-10-07 19:38:47pitrousetmessages: + msg145135
2011-10-07 19:37:28pitrousetnosy: + pitrou
messages: + msg145134
2011-10-07 19:30:54ezio.melottisetnosy: + ezio.melotti
messages: + msg145132
2011-10-07 18:30:03mikehoysetmessages: + msg145121
2011-10-07 17:38:23eric.araujosetmessages: + msg145114
2011-10-07 17:10:19mikehoysetmessages: + msg145106
2011-10-07 16:13:44eric.araujosetmessages: + msg145094
2011-10-06 22:59:50mikehoysetnosy: + mikehoy
messages: + msg145049
2011-08-01 13:33:21eric.araujosetstatus: pending -> open
versions: + Python 2.7, Python 3.2, Python 3.3
title: Provide reference to detailed installation instructions -> Missing items in installation/setup instructions
messages: + msg141509

keywords: + easy
2011-07-31 02:59:16orsenthilsetstatus: open -> pending

messages: + msg141456
2011-07-22 15:09:36eric.araujosetmessages: + msg140885
2011-07-22 14:22:05adam.woodbecksetmessages: + msg140881
2011-07-21 17:10:05adam.woodbecksetnosy: + adam.woodbeck
2011-07-12 07:15:17ncoghlansetmessages: + msg140175
2011-07-11 16:13:05eric.araujosetnosy: + eric.araujo
messages: + msg140141
2011-07-04 00:19:12orsenthilsetnosy: + orsenthil
messages: + msg139719
2011-06-28 23:56:34ncoghlancreate