Generate Idle help from Doc/library/idle.rst

[zware]

BPO	16893
Nosy	@birkenfeld, @terryjreedy, @ned-deily, @serwy, @merwok, @asvetlov, @roseman, @rovitotv, @vadmium, @zware
Files	issue16893_makefiles.diff: Adjust the Doc makefiles to add idledoc target issue16893_makefiles.v2.diff: Version 2 help.txt: rendered help text issue16893.v3.diff: Version 3, with changes to Doc/library/idle.rst issue16893-v4.diff sphinxview.py htmlhelp.diff

^{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 = <Date 2015-09-23.04:10:23.175>
created_at = <Date 2013-01-08.16:45:12.163>
labels = ['expert-IDLE', 'type-feature', 'docs']
title = 'Generate Idle help from Doc/library/idle.rst'
updated_at = <Date 2015-09-23.04:10:23.173>
user = 'https://github.com/zware'

bugs.python.org fields:

activity = <Date 2015-09-23.04:10:23.173>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2015-09-23.04:10:23.175>
closer = 'terry.reedy'
components = ['Documentation', 'IDLE']
creation = <Date 2013-01-08.16:45:12.163>
creator = 'zach.ware'
dependencies = []
files = ['28754', '29111', '29112', '29133', '36975', '40405', '40530']
hgrepos = []
issue_num = 16893
keywords = ['patch']
message_count = 44.0
messages = ['179362', '179615', '179708', '179710', '179846', '179954', '179959', '179960', '179961', '179962', '179963', '180096', '180104', '182115', '182298', '182300', '182301', '182546', '185706', '185726', '185729', '185732', '186035', '186040', '229706', '229712', '232105', '232233', '232798', '250132', '250153', '250194', '250238', '250434', '250439', '251180', '251182', '251191', '251284', '251285', '251389', '251398', '251399', '251403']
nosy_count = 13.0
nosy_names = ['georg.brandl', 'terry.reedy', 'ned.deily', 'roger.serwy', 'eric.araujo', 'asvetlov', 'markroseman', 'THRlWiTi', 'docs@python', 'Todd.Rovito', 'python-dev', 'martin.panter', 'zach.ware']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue16893'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5', 'Python 3.6']

[zware]

Lib/idlelib/help.txt and Doc/library/idle.rst contain almost exactly the same information, only formatted a bit differently. This issue is to suggest the merger of the two files, by way of creating help.txt from idle.rst as a part of the build or install process.

This could be as simple as merely copying the one to the other, but that of course leaves in place all reST directives that mean nothing to a simple text document. Thus, idle.rst should be processed to create help.txt. This could be done with sphinx/docutils, but to avoid having the CPython build process (not just the doc build process) depend on those tools, I think a very simple dedicated script could be created to do the processing without much trouble.

As far as I can tell, this new script would only have to do a few simple steps:

• Remove comments (including index markers, etc.)
• Remove reST roles (replace ":role:`" with "`", possibly remove "`" as well)
• Remove backslash escapes
• Remove (or undouble) double colons
• Replace "#." with "1.", etc.

Thoughts?

[rovitotv]

I think getting this issue fixed makes sense, it would save time and remove duplication.

[asvetlov]

I like the proposition in general, but files should be synchronized first.

[birkenfeld]

Note that Sphinx' "make text" output already should be suitable. We already update the pydoc topics with that on every release, so we could just as well do the same for the IDLE doc. No need for another separate script.

[rovitotv]

Andrew,
Zachary and I worked on another issue together to sync idle.rst with help.txt here:
http://bugs.python.org/issue5066

bpo-5066 is ready for commit if you have time by the way. Thanks!

[zware]

Georg:

Note that Sphinx' "make text" output already should be suitable. We
already update the pydoc topics with that on every release, so we could
just as well do the same for the IDLE doc. No need for another
separate script.

I take it this would mean generating help.txt and then checking it in? Otherwise, users who built their own Python would likely run into issues with IDLE not finding its help file, or would be required to have sphinx available. That's not quite what I had in mind, but if we already do it for pydoc topics, it sounds fine to me.

[asvetlov]

Regenerating idle.txt and committing it is fine to me.

[birkenfeld]

I take it this would mean generating help.txt and then checking it in? Otherwise, users who built their own Python would likely run into issues with IDLE not finding its help file, or would be required to have sphinx available.

Yes, it will be checked in.

That's not quite what I had in mind, but if we already do it for pydoc topics, it sounds fine to me.

I don't think we have to worry about it getting out of date quickly. Automatically generating the IDLE help at run time from a documentation source file is not posssible anyway, since the doc sources are not available in a standard location for installed Pythons.

[zware]

I don't think we have to worry about it getting out of date quickly.

Fair point :)

Automatically generating the IDLE help at run time from a documentation
source file is not posssible anyway, since the doc sources are not
available in a standard location for installed Pythons.

This isn't quite what I meant either; I had intended it to be done at either Python build or install time. Your method is much simpler, though, I like it.

That said, here's the diff between the (now) current Lib/idlelib/help.txt and the Sphinx make text output of Doc/library/idle.rst. I've not found where we've automated the pydoc topics generation, else I'd try to provide a patch to do this as well.

[birkenfeld]

The unified diff is not very helpful; I think somebody has to put the files side by side and merge.

The pydoc topics are built with a custom Sphinx builder implemented in tools/sphinxext/pyspecific.py -- but if we just want the vanilla text builder output it should be enough to add a Doc/Makefile target:

idledoc: BUILDER = text
idledoc: SOURCES = library/idle
idledoc: build
@echo "Build finished; now copying build/text/library/idle.txt to ../Lib/idlelib/help.txt."
@cp build/text/library/idle.txt ../Lib/idlelib/help.txt

and I add a step to PEP-101 to run this.

[birkenfeld]

To make it actually work, replace "library/idle" by "library/idle.rst".