[docs] [issue16893] Generate Idle help from Doc/library/idle.rst

[Terry J. Reedy]

Terry J. Reedy added the comment:

The goal of this issue is that Idle -> Help -> IDLE Help display a good-looking, accurate help page based on Doc/library/idle.rst.  The current Lib/idlelib/help.txt is neither good-looking nor accurate and must somehow be replaced, even if by temporary means, before another release (2.7.9 was missed, 3.4.3 is coming in January).

Ned's gave some comments on the alternatives in msg185726.  I am extending those (and in some places implicitly referring back to them) based on further thinking and investigation.  A summary of what I currently think might be best:

if Windows:
  open .chm to Idle page
else:
  try:
    open offline docs to Idle page
  except failure:
    open generated .txt without `s.

The easiest alternative would be to display the online python.org page in a browser.  It looks nice, has a sidebar index, and access to the rest of the docs.  An obvious problem is that this requires a browser and online access, either of which might be lacking in a classroom or when one is away from home base.  More subtle is that Idle features can be changed or added at any time.  The online docs, generated daily from the repository, should reflect the repository version of Idle.  Released versions need a doc frozen at the time of release.

Still easy, perhaps, would be building Doc/build/html/library/idle.html and copying it to idlelib/help.html as part of the release process*, and changing the code to display that instead 

However as Zack hinted ("clean up the output a bit"), this file is not a standalone file.  It has many links to files in '..', such as "Index" and "Copyright"; these would have to be removed completely as the text is useless without the link.  For cross-reference link, such as 'Tkinter' or 'sys.path', the text should be left but the linkage removed.  In both cases, clicking the link gives a File not Found page. The broken links to javascript formatting files in '../.source' appears to be ignored and the formatting simply not done.  So the page index is at the bottom of the page instead of the sidebar.

* The beginners who most need the help doc are running installed Python, not respository builds, so the latter concerns me less.

But why make an off-line page when there already is one in off-line docs?  I presume that the linux and osx doc urls just need 'index.html' replaced with '/library/idle.html'.  The 'standard location' for linux is x.y.z specific.  The python2 rpm location does not seem to be.  The osx location I will not guess about.

For Windows, startfile('x.chm') does the same as double-clicking x.chm in Explorer, which is to open the file with the Help Control, with a nice sidebar for contents, index, search, and favorites. Adding "::/library/idle.html" does not work because it makes the path invalid.  But with an special prefix

>>> os.startfile("mk:@MSITStore:c:/programs/Python34/Doc/python342.chm::/library/idle.html")

opens the page in InternetExplorer.  However, there is no sidebar and the page has to be clicked on the taskbar to make it visible.  In 1 of 4 tries, the above failed.

An answer to this StackOverflow question

https://stackoverflow.com/questions/11076952/open-chm-file-at-specific-page-topic-using-command-line-arguments?rq=1

prompted me to try

>>> subprocess.Popen("hh ms-its:c:/programs/Python34/Doc/python342.chm::/library/idle.html")

This opens the chm doc with the help control (and sidebar) to the Idle page, just as I wanted.  Since Doc/pythonxyz.chm is part of the installation, I think this is the solution for Windows.  The one glitch is that testing that the exact code in the repository works needs to be done with a pre-final install.  That is already true of testing that "Help -> Python docs F1" opens the .chm to the index page.  These both should be part of a new installed idle test file.

After generating html.txt from idle.rst, the backticks could be filtered out.  It would be close to what we have now.  Is there any need to keep it as a backup for non-Windows systems?  If not, I would be inclined to delete it.

For repository builds, users could go to the online Idle page.  I might even look for ../../Misc and if present, open it directly.  That page would be at most a day out of date.

----------
assignee:  -> terry.reedy

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16893>
_______________________________________