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

[Martin Panter]

Martin Panter added the comment:

The tests seem to have grown a new Deprecation Warning (triggered when run with 
python -bWall). Looks like this may be a side effect of revision 2d808b72996d.

[160/392] test_idle
/media/disk/home/proj/python/cpython/Lib/idlelib/EditorWindow.py:88: 
DeprecationWarning: EditorWindow.HelpDialog is no longer used by Idle.
It will be removed in 3.6 or later.
It has been replaced by private help.HelpWindow

  helpDialog = HelpDialog()  # singleton instance, no longer used

--
nosy: +martin.panter

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Roundup Robot added the comment:

New changeset 26e819909891 by Terry Jan Reedy in branch '2.7':
Issue #16893: Move idlelib.EditorWindow.HelpDialog deprecation warning
https://hg.python.org/cpython/rev/26e819909891

New changeset c607004a98bf by Terry Jan Reedy in branch '3.4':
Issue #16893: Move idlelib.EditorWindow.HelpDialog deprecation warning
https://hg.python.org/cpython/rev/c607004a98bf

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

Through the contributions of several people, Zack's key idea, that Idle 
documentation should have a single source, idle.rst, has come to fruition. So I 
think it time to close this.  I already mentioned #25198 for improving the 
tkinter viewer. I also opened #25218 for revising Zack's patch and possibly 
using an 'idledoc' target in the release process.

--
resolution:  -> fixed
stage: needs patch -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

Thank you for reporting this. My general problem is that idlelib was only 
informally private until PEP434 and I only started adding 'private' and 
'deprecated' to the code a week ago.  So I am trying to make changes in 
existing versions while not breaking even unlikely uses of the current API. The 
specific problem is the the class init method *is* used -- to create an unused 
instance -- on import.

  helpDialog = HelpDialog()  # singleton instance, no longer used

The patch fixes the problem by moving the deprecation to the show method, which 
Idle really does not now call.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Roundup Robot added the comment:

New changeset 855484b55da3 by Terry Jan Reedy in branch '2.7':
Issue #16893: Add idlelib.help.copy_strip() to copy-rstrip Doc/.../idle.html.
https://hg.python.org/cpython/rev/855484b55da3

New changeset df987a0bc350 by Terry Jan Reedy in branch '3.4':
Issue #16893: Add idlelib.help.copy_strip() to copy-rstrip Doc/.../idle.html.
https://hg.python.org/cpython/rev/df987a0bc350

New changeset f08437278049 by Terry Jan Reedy in branch '3.5':
Issue #16893: Add idlelib.help.copy_strip() to copy-rstrip Doc/.../idle.html.
https://hg.python.org/cpython/rev/f08437278049

New changeset 09ebed6a8cb8 by Terry Jan Reedy in branch 'default':
Issue #16893: Add idlelib.help.copy_strip() to copy-rstrip Doc/.../idle.html.
https://hg.python.org/cpython/rev/09ebed6a8cb8

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

NEWS entries are done.

I added a function, copy_strip, to help.py to rstrip (in bytes mode) idle.html 
as it copies to help.html.  (I changed the name to better remember which is 
which.)  In my .bat file, with Doc as current directory, I use
  ..\pcbuild\python_d.exe -c "from idlelib.help import copy_strip; copy_strip()"
I could change the if __name__ block so that
  ..\pcbuild\python_d.exe -m idlelib.help copy_strip
would work.  Either way, I would like to add 'idlehelp' to makefiles.  But not 
tonight.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

I committed a patch that works well enough for release as it. I attached the 
diff for changed files in case anyone wants to view in Rietveld. 

Still to do for this issue:

* Automate getting the 2.7 and earliest 3.x idle.html copied to idlelib and 
whitespace-normalized. (Commit/push should stay manual.) Several lines have 1 
to many blanks at the end, while the file lacks a final \n.  See e66fbfa282c6. 
(These anomalies come from Sphinx; idle.rst has been normalized to be checked 
in.)

I have a .bat file that builds any and copies as needed.  I will to add a pass 
through Idle's trailing-whitespace deleter, which did just what was needed to 
commit. (Patchcheck.normalize_docs_whitespace does a here unneeded comparision 
(always unequal), creates an unwanted and nuisance .bak, and does not appear to 
work when the last list has no '\n'.)

When I have automation working for me, I would like to add make targets for 
others to use (Zach's patch 4).

* Edit idle.rst

I will push NEWS and idlelib.NEWS entries separately, along with others for 
Idle.

I opened new issue #25198 for further viewer improvements (and bug fixes, if 
any).

--
Added file: http://bugs.python.org/file40530/htmlhelp.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Roundup Robot added the comment:

New changeset 4038508240a1 by Terry Jan Reedy in branch '2.7':
Issue #16893: Replace help.txt with idle.html for Idle doc display.
https://hg.python.org/cpython/rev/4038508240a1

New changeset 52510bc368f8 by Terry Jan Reedy in branch '2.7':
Issue #16893: include new files
https://hg.python.org/cpython/rev/52510bc368f8

New changeset 2d808b72996d by Terry Jan Reedy in branch '3.4':
Issue #16893: Replace help.txt with idle.html for Idle doc display.
https://hg.python.org/cpython/rev/2d808b72996d

New changeset e66fbfa282c6 by Terry Jan Reedy in branch '2.7':
Issue #16893: whitespace in idle.html.
https://hg.python.org/cpython/rev/e66fbfa282c6

New changeset 9b79a4901069 by Terry Jan Reedy in branch '3.4':
Issue #16893: whitespace in idle.html.
https://hg.python.org/cpython/rev/9b79a4901069

New changeset 1107e3ee6103 by Terry Jan Reedy in branch '2.7':
Issue #16893: whitespace in help.py.
https://hg.python.org/cpython/rev/1107e3ee6103

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Roundup Robot added the comment:

New changeset e749080fa0f9 by Terry Jan Reedy in branch '2.7':
Issue #16893: finish deprecation.
https://hg.python.org/cpython/rev/e749080fa0f9

New changeset ff0270e9bdfb by Terry Jan Reedy in branch '3.4':
Issue #16893: finish deprecation.
https://hg.python.org/cpython/rev/ff0270e9bdfb

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Zachary Ware]

Zachary Ware added the comment:

I'd be happy to work on making an 'idledoc' target for the Doc/ makefiles that 
works with Mark's viewer.  I can't guarantee any kind of timeframe, but the 
idledoc target wouldn't be necessary right off the bat; it could be done after 
the main bulk of the patch is committed.

As far as reST comments, the syntax is:

"""
.. This is a comment.
   This is still the same comment.
   And more of the same comment.

This is no longer part of the comment
"""

See http://docutils.sourceforge.net/docs/user/rst/quickref.html#comments

--
versions: +Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

In msg185726 Ned said "Ironically, the Tk text widget is perfectly capable of 
rendering richer text styles." He was and is correct.  Mark Roseman offered to 
take up the challenge.  In spite of my skepticism, he went ahead and built 
sphinxview around HTMLParser.  This reduced the core of the problem to "for 
each tag, content, and end tag, what state change or text insertion is needed. 
The result is simple enough for me to understand and even edit.

I sent Mark a detailed comparison of the Firefox rendering of idle.html and his 
tk rendering.  He replied with a new version whose output is essentially 
identical to Firefox's (minus links), including the green example box.  I 
intend to use a third version and will work on a full patch.

When running in a repository clone, Idle could access 
../../Doc/build/html/library/idle.html.  But for installations, idle.html needs 
to be in idlelib.  I guess the only was to guarantee this everywhere (excepting 
overt downstream removals) is to commit it into the repository, unlike most 
other files built from .rst files). 

To help make sure this happens, I would like to add a comment at the top of 
idle.rst.  The devguide sentence on comments is unclear to me. Will the 
following work?
.. # After editing this, also build html, copy idle.html to idlelib,
   test, and upload or commit the html diff also.

It would be nice if the copy and commit process were added to the release 
process, but I will go ahead even without that.  A nicely rendered, slightly 
out-of-date .html will be a great improvement over the current situation.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Mark Roseman]

Mark Roseman added the comment:

Ok. In case you're curious or might find it useful elsewhere, I've attached 
sphinxview.py, which renders the HTML into a text widget (with formatting, it's 
not converted to plain text).

--
Added file: http://bugs.python.org/file40405/sphinxview.py

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

This looks more maintainable than I expected, so I will definite try it out.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Mark Roseman]

Changes by Mark Roseman :


--
nosy: +markroseman

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[irdb]

Changes by irdb dalba.w...@gmail.com:


--
nosy: +irdb

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue16893
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[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 rep...@bugs.python.org
http://bugs.python.org/issue16893
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Roundup Robot added the comment:

New changeset 283c364c372a by Terry Jan Reedy in branch '2.7':
Issue #16893: Update Idle doc chapter to match current Idle and add new
https://hg.python.org/cpython/rev/283c364c372a

New changeset 2fc341c6e314 by Terry Jan Reedy in branch '3.4':
Issue #16893: Update Idle doc chapter to match current Idle and add new
https://hg.python.org/cpython/rev/2fc341c6e314

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue16893
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Roundup Robot added the comment:

New changeset 6db65ff985b6 by Terry Jan Reedy in branch '3.4':
Issue #16893: For Idle doc, move index entries, copy no-subprocess section
https://hg.python.org/cpython/rev/6db65ff985b6

New changeset feec1ea55127 by Terry Jan Reedy in branch '2.7':
Issue #16893: Update 2.7 version of Idle doc to match 3.4 doc as of the just
https://hg.python.org/cpython/rev/feec1ea55127

--
nosy: +python-dev

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue16893
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy added the comment:

I have avoided editing the Idle docs because of this issue, but idle.rst needs 
some corrections and updates now, and will soon need some additions.  I want to 
only edit idle.rst. So I want to resolve this issue soon.

As I mentioned before, I think the best idea is Ned's: copy 
Doc/build/html/library/idle.html to idlelib (as help.html for now) and change 
the 'IDLE Help' code to display it in a browser.  This will be easy and will 
end the duplication and DRY violation that is the goal of this issue.

Zach, can you produce a makefiles.v4 patch (without .rst changes) that patches 
the makefiles to add a target do the copying?  The same patch (or another) 
should add idlelib/help.html to .hgignore so idle developers and testers can 
'make' the new target without committing it.  Georg can then update PEP 101 
with the new release step.

This change will provide a nicely formatted, always-available local copy that 
should match the installed micro-version.  Because of PEP 434, later online 
versions of the doc may contain changes that do not apply to the installed 
version.

After this is done, and anything in help.txt but not in idle.rst is moved, 
help.txt will be deleted.

issue16893.v3.diff mixes together changes for this issue and a separate issue 
of editing idle.rst.  I will separately apply some of your mising changes, but 
I don't think I like adding the new separators and even more whitespace.  Also, 
I assume that 'Control' in .txt was changed to 'C' in .rst because OSX uses 
'Command' instead of 'Control' and 'C' stands for either.  That is aside from 
the issue of abbreviating something used repeatedly.  Anyway, I think this is a 
discussion for another tracker issue.

--
stage:  - needs patch
title: Create IDLE help.txt from Doc/library/idle.rst - Generate Idle help 
from Doc/library/idle.rst

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue16893
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Zachary Ware]

Zachary Ware added the comment:

Sure; here's a patch.  I suspect we may want to try giving Sphinx some 
different options to clean up the output a bit, but I'm not experienced enough 
with Sphinx to have any specific suggestions.

--
Added file: http://bugs.python.org/file36975/issue16893-v4.diff

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue16893
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com