Documentation for IDLE states:

    Starting IDLE on UNIX 
    On Unix, just type "idle" at a command prompt. This should bring
    up a Window similar to the one above. (If it doesn't, look for
    the "idle" script in the Tools/idle directory in the Python source
    distribution.)

http://www.python.org/idle/doc/idlemain.html

I believe that is obsolete, I cannot see a Tools/idle directory in 
either 2.5 or 2.6. Perhaps better instructions might be:

    (If it doesn't, run "python LOC/idlelib/idle.py" where LOC 
    is the location of your Python source distribution, usually 
    /usr/lib/python*.)

or similar.

LOL. That doc was apparently last revised in 2000 for the IDLE released
with 1.5.2 (see screenshot).  Other needed updates I see are: 'Shell'
and 'Options' have been added to the menu line; we now have unicode
text; screenshots look different (and nicer) on newer Tk on WinXP and
could/should be redone.

If it were decided to update this and add it to the doc package, I would
help in some way.

Well, having nice full docs for IDLE would be nice, but I won't do
anything on this matter except committing a full patch :)

Is there an HTML to acceptable RST converter?

I don't know any. But since rst is so lightweight, it is usually not too
much of a pain to just copy the text from the browser and reintroduce
formatting because you're likely to have to go over and edit the whole
content anyway.

This looks like a perfect match for GHOP.

Attached is a patch updating the IDLE web documentation as well as the help file displayed when you click the Help -> Idle Help menu item in IDLE. It looks like the IDLE web documentation was lifted directly from the help file at some point and they have gotten out of sync.

The section of the document describing starting IDLE was updated in March of 2009, so I've left that alone. I've updated the Menu option descriptions in both files, including: adding missing items, making the help file and web document descriptions the same, and using a consistent format.

The patch is against release27-maint.

I reviewed the texts, applied the patches, ran idle, edited Demo/classes/Dates.py run module inside Idle. Generated the docs inside Doc, with make html and reviewed the IDLE doc in ~/python/py3k/Doc/build/html/library/idle.html?highlight=idle

Only in the 3.2 tree.

This is a good patch but it is rather out of date and won't apply.  I will patch the patch and maybe somebody can apply it this time.  Expect a new patch by 11/26/2012.

This patch is an extensive refactoring of help.txt and idle.rst. The first thing I did was merge issue5066.patch from jesstess into the current idle.rst file, because the original patch from jesstess was so old it had to be merged by hand into the 3.4 source code.  Then I compared what the merge document said with the actual menus of IDLE and made several corrections because of missing menu options.  Finally I refactored the help.txt based on idle.rst and created the resulting patch. Several capitalization's were fixed along with many inconsistencies between the two files.  

I have not tested on 2.7 only 3.4.  My plan is to test with 2.7 and create another patch by end of the week 12/2/2012.

The original help.txt and the patched version still mixes tabs and spaces. This is a minor point, but perhaps all the tabs should be expanded.

Also, the section on running IDLE without a subprocess should not be removed until version 3.5. See #16123.

Version 2 of the patch change include:
-help.txt removed all tabs and replaced with spaces, as suggested by Roger
-help.txt re-inserted the section on running IDLE without a subprocess as suggested by Roger
-Added a note on line 162 (idle.rst) about how the Python Community standard is to use spaces and not tabs as suggested by ezio
-Line 340 (idle.rst) where the Emacs bindings are rendered seemed to work fine on my computer without the spaces but I think ezio is correct spaces should be present so I added them
-Line 354 (idle.rst): are restricted to four spaces due to TCL/Tk issues.)s/issues/limitations/ so I replaced issues with limitations

Thanks for the feedback Roger and ezio!

For version 2 of the patch 
-Line 340 (idle.rst) where the Emacs bindings are rendered seemed to work fine on my computer without the spaces but I think ezio is correct spaces should be present so I added them

******SHOULD BE******
-Line 340 (idle.rst) where the Emacs bindings are rendered seemed to work fine on my computer without the empty line between entries but I think ezio is correct empty lines should be present so I added empty lines just to be safe

A "ping" on this bug since it has not had any forward movement.  Can somebody please review and or commit?  Thanks.

Hi Todd, I can't commit, but I have a review in the works for you.

Thanks much appreciated!

Sent from my iPhone

On Jan 4, 2013, at 1:07 PM, Zachary Ware <report@bugs.python.org> wrote:

> 
> Zachary Ware added the comment:
> 
> Hi Todd, I can't commit, but I have a review in the works for you.
> 
> ----------
> nosy: +zach.ware
> 
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue5066>
> _______________________________________

I wonder, is there any really good reason to keep a separate Lib/idlelib/help.txt, or can Doc/library/idle.rst be used for its purpose (with or without a small amount of processing to, for instance, remove comments and extra backslashes)?  Both have most of the same information, and reST is designed to be readable anyway, so I don't see much point in keeping them separate.

Zachary,
   I like your idea about joining idle.rst with help.txt but I think that should be covered under a separate bug issue.  The way I see it this bug is about fixing the current documentation.  So I suggest you open up a new issue and get people's take on it.  I think a parser could be run at installation to convert idle.rst to help.txt or maybe IDLE could be modified to simply render idle.rst correctly.  I am not sure what the best approach will be.

PS Thanks for the review I should have your suggested changes integrating into a new patch today.

Right you are, Todd; I'll get another issue opened for that soon.

Zachary,
   Thanks for your excellent review!!!!  Your feedback was very helpful for making the patch even better.

Based on Zachary's comments I have uploaded a new version of the patch which is version 3.

Idle needs to find its text help files at runtime, so they are installed as data alongside with the code.  The rst doc files however can be installed anywhere or not installed at all, so we can’t change Idle to look for them.

An alternate idea to avoid duplication could be to copy the rst file to the code directory at build time.

Regardless of the topic of merge, the suggested improvements for both idle.rst and help.txt are great! Thanks for working the patch, Todd.
I am +1 with the changes. If no else has any comments, I can go ahead with committing this.

I'd like to see Éric, Ezio, and my comments on v3 in Rietveld addressed, but after that I'm good with it :)

Issue 16893 has been filed to deal with the idea of merging the files.

Thanks Senthil but I don't deserve all the credit this issue is a team effort with lots of help from Zach, Éric, and Ezio.  All of which have improved the patch's quality a great deal.  Hopefully we can address the issues then let you make the commit soon.

I took all the comments and created a new patch version 4 which should address all the issues.  Thanks for the excellent review and support from everybody.  I think this patch is a much higher quality now.

Version 4 looks good to me!

New changeset d1ef91025d70 by Andrew Svetlov in branch 'default':
Issue #5066: Update IDLE docs
http://hg.python.org/cpython/rev/d1ef91025d70

Pushed. Thanks.