I would like to propose a new HOWTO discussing IDLE from a user's perspective. I feel that the current documentation at http://docs.python.org/3/library/idle.html is not sufficient to be pointed to a newbie programmer or someone who wants to teach his/her students to IDLE. For example, being an experienced person myself, I didn't know how to start IDLE on Linux! Whether it was a separate package, or whether it was already installed (That may be my own shortcoming, but never the less).

I started a document this morning which can be seen here [1]. The source is here[2]

[1] http://amitsaha.github.com/site/notes/articles/idle/article.html
[2] http://amitsaha.github.com/site/notes/_sources/articles/idle/article.txt

I am putting up my hand to write the HOWTO and maintain it for 2.7 and 3.3+.

Comments?

I think it is a great idea.....

The Python documentation is written with restructured text. See the Python Developer's Guide here:
http://docs.python.org/devguide/documenting.html

Restructured text is not difficult please let me know if you need help I would be glad to assist.

What you have is a good start but it will have to be reformatted then submitted as a patch so it can be committed. In addition you have to complete a Python Contributor Agreement. Please spend a little time looking over the Python Developer's Guide. Thanks.

I agree that improving IDLE's docs would make it easier to learn and use. There is a tangentially related issue: bpo-16893.

Hi Todd,

I just signed the Python contributor agreement electronically.

You probably missed the link to the rSt source in my original report. Here it is [1]. I would want this HOWTO to cover all aspects of IDLE from an user's perspective.

I have some ideas about what to add, but I would like to hear from you as well.

Thanks.

[1] http://amitsaha.github.com/site/notes/_sources/articles/idle/article.txt

Yes I missed the link sorry. Can you add the rst file to Doc/faq in the tip of the repository then do a hg diff and post the patch as an attachment to this issue? At that point I will review and send any changes or edits with the review system. Others can suggest changes as well.

Adding the patch here. I am not sure about how to add the screenshots, so I haven't done them.

Just attached the document as a patch (note that I have placed in doc/howto).

Thanks for the comments.

I left a few comments on rietveld.
I wonder if it's better to make two separate versions, one for py2 and one for py3, and avoid repeating things (like the name of the packages) twice.

You should also be able to include the images in the patch by using "hg add" locally. This should include them when you do "hg diff > idle.patch" (if it doesn't work you might have to set "git = on" (see http://docs.python.org/devguide/committing.html#minimal-configuration)).

Hi Ezio, thanks for your review comments.

I will make the changes to the document, and also add the images in a later patch.

I do agree that repeating package names for Python 2 and Python 3 is perhaps not an ideal way. I am also trying to think of other ways to justify having two separate documents: may be the code samples? print 'Hello world' versus print('Hello World') ?

Thanks.

Ezio,
I left a few comments on rietveld. This is a really nice start to a great FAQ. Thanks for your contribution I think Python needs a nice FAQ on IDLE. You might want to add some detail about the right click menu which allows a user to cut, copy, paste, and set breakpoints. I think a section on the debugger would be excellent.

Hi Todd, thanks for your comments. I wanted to clarify that I intend to make this a HOWTO, not a FAQ.

I hope that's fine?

-Amit.

I added a few more comments.

To clarify, when I said two documents, I meant that there will be only a single HOWTO, but on 2.7 it will be specific to Python 2, whereas on 3.x it will be specific to Python 3.

Thanks Ezio. I am almost done with incorporating the changes suggested and will submit a patch sometime in the next day or so.

Sorry about using the wrong word, I should of used HowTo not FAQ. I really meant to suggest replacing guide with the word HowTo. A HowTo would be perfect!!!! Sorry about the confusion. Thanks again.

I have tried to incorporate most of the suggestions and made some other changes as well. Hope it looks better now.

I haven't yet split it into two separate versions.

This is a great idea, thank you.

FYI You can share text and images with a diff file: if you call “hg add path/to/images” and create the diff with the --git option, it will use an extended unified diff format which includes binary changes. Our review system is not compatible with that format though, so you can simply attach the files here.

Hello Éric Araujo, thanks. Oh I thought it did support, and hence I created the diff in exactly the way you mention.

i also went ahead and tested it by 'hg import' -ing it into a cpython clone and i was all excited to see all my images there :-)

But, yeah I can certainly attach the images separately.

Hello, I just wanted to check if I should attach the image files separately and submit the text as a diff?

Thanks.

(If someone else wants to take this before I get to it, feel free. But there seems to be enough support to add something eventually.)

It seems that Rietveld is able to ignore the binaries, but in the future, lets separate the text and images. If nothing else, the images should stay the same while the text gets updated patches.

Looking at http://docs.python.org/3/howto/index.html, I think the title should begin with Idle or IDLE, but if the latter, not include HOWTO as one SHOUT is enough. I think it should be in its alphabetical position after Functional Programming. I have no idea why argparse and ipaddress are out of order.

I think there should be a section on using the shell before using the editor.

From a command line (at least on Windows, when not in the directory containing idle.py) 'python -m idlelib' is the easiest way to start. Within a Python program, 'import idlelib.idle' starts it. I plan to add a new section to the docs for this, but it might be worth repeating.

I will look more closely at the text another time.

Cheryl, what do you think of the revised patch? I imagine it needs some updating for *nix, but does it seem useful to a beginner?

I think it's a good start, but may need some tweaking. For example, the
Menu options should probably somehow stand out from the rest of the text.

I think it would be useful for a beginner, depending on how much of a
beginner they are and how they got to this page. For example, if I wanted
to learn Python and had no prior programming experience, most likely I
would google 'learn python' (or maybe even just 'learn to program') and
check out those links. Some results, like the Tutorial in the python.org
docs, focus on getting Python installed and using the interactive
interpreter. There doesn't seem to be anything in the python.org docs
(except for the FAQ) that suggest using IDLE. Although, the FAQ might be
one of the first places a beginner would look, so maybe a link from there
to the HOWTO would be helpful. I think showing how to install IDLE and use
it is important, and that alone would make this page useful. The current
IDLE doc page has the command line usage in the middle of the page, but
doesn't really just answer how do I install it and how do I run it?

So, assuming a beginner is following some tutorial, they get to a point
where they need an editor. Following the instructions for installing any
program can be tricky. Heck, even installing Python might have been
tricky, so good for them if they got this far. But, without any
instructions for getting IDLE to run, they are left to googling for it. It
would be great for the python docs can have a step by step installation
instruction and even troubleshooting. Then, as this HOWTO does, explain
what opens up and how to use the editor, etc. As I've recently experienced
with git, I find it frustrating to spend half a day trying to get something
to work when it should be easy. This page could be a one page
introduction/reference so that someone doesn't have to cobble together
answers from all over the internet to questions they didn't even know to
ask.

Thanks. This is helpful and got me started thinking.

I don't want to duplicate the reference doc too much, but a reference is just that, a reference. The menu items are discussed in the order they appear, not the order a beginner might use the most common ones.

Judging from Stackoverflow questions, covering platform specifics is needed. People seem to miss the following: Python runs IDLE; IDLE hands user code to Python to execute. Output and error messages come from Python, not IDLE. If you want python to import 3rd party modules, one must install the module for the Python used to run IDLE. (I have answered at least 3 variations of this question.) Anyway, I realize that I have a source of frequent beginner questions and problems. If we have answers in a How-To, I can quote and suggest that people read it.

Amit, do you wish to continue with this?

Is this a duplicate of #59149?

There are quite a few possibilities for this/the other issue:

• New page which would be linked in the others below
  • tutorial
    • "Using Python" --- Somehow not a single mention
  • HOWTO
• Extend Lib/idle
  • Add a picture of interface with labels, quickstart guide etc
• Extend Using (both under Linux install and Editors and IDEs)

Using currently as a link to the wiki which references IDLE already however I asked the docs team and they do not mind a duplicate entry.

I propose we do

• Using Linux Install section add IDLE install guide
• Using Editors and IDEs add entry about IDLE and link to install guide
• Link to install guide in idle.html

I didn't know how to start IDLE on Linux!

The authors main issue has been addressed now. What else are we thinking of doing?

@Mariatta I've heard you have plans on redesigning the tutorials, maybe idle could be included in them? I see many beginners who don't fully understand what its for.