IDLE HOWTO

[AmitSaha]

BPO	17583
Nosy	@terryjreedy, @ezio-melotti, @serwy, @merwok, @rovitotv, @csabella
Files	idle.patch: IDLE HOWTO initial patch idle.patch: IDLE HOWTO Patch Rename README to README.rst and enhance formatting #2 (includes screenshots)

^{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/terryjreedy'
closed_at = None
created_at = <Date 2013-03-30.23:12:36.267>
labels = ['expert-IDLE', 'type-feature', '3.10', 'docs']
title = 'IDLE HOWTO'
updated_at = <Date 2020-06-07.20:58:06.229>
user = 'https://bugs.python.org/AmitSaha'

bugs.python.org fields:

activity = <Date 2020-06-07.20:58:06.229>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'IDLE']
creation = <Date 2013-03-30.23:12:36.267>
creator = 'Amit.Saha'
dependencies = []
files = ['29641', '29654']
hgrepos = []
issue_num = 17583
keywords = ['patch']
message_count = 21.0
messages = ['185600', '185609', '185610', '185624', '185629', '185688', '185693', '185696', '185701', '185702', '185769', '185776', '185790', '185827', '185874', '185876', '188759', '193075', '296382', '296394', '296395']
nosy_count = 9.0
nosy_names = ['terry.reedy', 'ezio.melotti', 'roger.serwy', 'eric.araujo', 'docs@python', 'Todd.Rovito', 'Al.Sweigart', 'Amit.Saha', 'cheryl.sabella']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue17583'
versions = ['Python 3.10']

[AmitSaha]

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?

[rovitotv]

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.

[serwy]

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

[AmitSaha]

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

[rovitotv]

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.

[AmitSaha]

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.

[ezio-melotti]

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

[AmitSaha]

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.

[rovitotv]

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.

[AmitSaha]

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.

[ezio-melotti]

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.