Automate creation of idlelib/help.html from Doc/.../idle.html

[terryjreedy]

BPO	25218
Nosy	@terryjreedy, @zware

^{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 2015-09-23.03:42:34.985>
labels = ['expert-IDLE', 'type-bug', '3.7', 'build']
title = 'Automate creation of idlelib/help.html from Doc/.../idle.html'
updated_at = <Date 2017-09-11.20:55:28.824>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2017-09-11.20:55:28.824>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = False
closed_date = None
closer = None
components = ['Build', 'IDLE']
creation = <Date 2015-09-23.03:42:34.985>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 25218
keywords = []
message_count = 2.0
messages = ['251402', '301902']
nosy_count = 2.0
nosy_names = ['terry.reedy', 'zach.ware']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue25218'
versions = ['Python 3.6', 'Python 3.7']

Linked PRs

• gh-132723

[terryjreedy]

This continues bpo-16893, which replaced help.txt with help.html for the Idle doc display. It also replaced the display classes with new classes in help.py. I currently create help.html in a .bat file. With Doc as current directory, it uses ..\pcbuild\python_d.exe -c "from idlelib.help import copy_strip; copy_strip()" With a change to the help.py if __name__ block so that ..\pcbuild\python_d.exe -m idlelib.help copy_strip would work.

This issue is first about revising Zack Ware's makefile patch, https://bugs.python.org/file36975/issue16893-v4.diff, which adds an 'idledoc' target. It is attached to bpo-16893. It needs 'copy' replaced by 'copy, strip, and rename'. The command above requires finding a compatible python.exe, and I do not know if that is a problem.

In normal use, 'idledoc' should only be invoked for the earliest 3.x getting maintenance patches, and the result merged forward.

If this is resolved, it would be nice if the new 'idledoc' target were built as apart of the release process, and any changes checked in. But the latter should currently still be done for all 3.x branches

[terryjreedy]

Zach, I currently build idlelib/help.html by first building a complete doc set and then copying from Doc/.../idle.html, stripping trailing whitespace on the say. One problem is that the result has a lot of extraneous stuff aside from the doc text itself: the code for the header, sidebar, and footer. These are a nuisance when committing changes and for extracting just the text we want.

I would prefer to create a clean .html from Doc/library/idle.rst that just has the code for the doc, without the extraneous matter. Do you know how? I looked in Doc/make.bat and it says it will not work on single files.

EDIT: fixed in #129873.

[StanFromIreland]

Sphinx can be run with an empty conf like so:

html_theme = 'basic'
html_static_path = []
html_js_files = []
html_css_files = []
html_show_sourcelink = False
html_show_copyright = False
html_show_sphinx = False

And then stripping everything that is not in <section id="idle"> returns the desired result.*

Maybe an action could be added that runs when idle.html is modified? It would build, extract the file and then create the conf and then a simple bash script with a counter to clean up.

Otherwise we have to manually update with each PR. (This should probably be done in the meantime as it has not been done for a while)

*The only thing left is :source: but maybe we can just modify the docs to a link to clean that up?

[terryjreedy]

I now use a custom .bat file to run sphinx and copy-trim the result. This works as long as I am the only one editing idle.rst and remember to run the .bat file.

[encukou]

FWIW, there is some tooling for help() topics in Doc/tools/extensions/pydoc_topics.py and release-tools.

[StanFromIreland]

Adding a workflow for when a PR modifies /Doc/Lib/idle.rst would be better than updating with releases in my opinion.

[terryjreedy]

@StanFromIreland In PR #132723 you tried and due to problems rejected idea of auto updating help.html if older that idle.rst. I want to consider your alternative of adding a check. I am not sure if it passing should be required. It might work better with Z. Ware's idea of adding 'idledoc' target to makefile. What do you think?

[StanFromIreland]

Adding the makefile target would be good, we already have one for regeneration of pydoc-topics.

We could add a check to the existing check generated files workflow. Making it optional is also possible.

We could also consider adding it to the release process, like pydoc-topics.