Repository navigation
Include HTML docs with Windows installer instead of CHM #91242
Description
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/zooba'
closed_at = None
created_at = <Date 2022-03-21.20:44:27.135>
labels = ['type-feature', 'OS-windows', '3.11']
title = 'Include HTML docs with Windows installer instead of CHM'
updated_at = <Date 2022-03-23.16:14:17.736>
user = 'https://github.com/zooba'bugs.python.org fields:
activity = <Date 2022-03-23.16:14:17.736>
actor = 'steve.dower'
assignee = 'steve.dower'
closed = False
closed_date = None
closer = None
components = ['Windows']
creation = <Date 2022-03-21.20:44:27.135>
creator = 'steve.dower'
dependencies = []
files = []
hgrepos = []
issue_num = 47086
keywords = ['patch']
message_count = 14.0
messages = ['415701', '415735', '415736', '415819', '415822', '415824', '415825', '415827', '415828', '415829', '415830', '415848', '415866', '415884']
nosy_count = 7.0
nosy_names = ['terry.reedy', 'paul.moore', 'tim.golden', 'ned.deily', 'zach.ware', 'steve.dower', 'mdk']
pr_nums = ['32038', '32075']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue47086'
versions = ['Python 3.11']
Activity
zooba commentedon Mar 21, 2022
CHM is getting too hard to handle (see e.g. bpo-47051 for the latest issue), so let's just bite the bullet and ship the HTML docs instead.
zooba commentedon Mar 22, 2022
New changeset 3751b6b by Steve Dower in branch 'main':
bpo-47086: Remove .chm from Windows installer and add HTML docs (GH-32038)
3751b6b
zooba commentedon Mar 22, 2022
Leaving this open and assigned to myself for a couple of days to deal with any other fallout. In particular, I wasn't able to test the (minor) changes to the publishing steps (e.g. GPG signing), so will have to wait for the next release to see what works/doesn't there.
ned-deily commentedon Mar 22, 2022
If you remove the .chm file from the Windows installer, I believe IDLE needs to be updated to look for the installed html files instead (see Lib/idlelib/editor.py).
And does this mean we should no longer produce .chm files at all for 3.11+? If so, there is work to be done in the Doc section of the repo (Makefile, make.bat, README.rst tools/* all have references to .chm and .hhp files). I guess other than the references to chm files in the docs, this change would not otherwise affect the on-line docs building system.
(Nosying Terry and Julien as subject experts.)
zooba commentedon Mar 22, 2022
Good call on IDLE, I didn't even think to check there (there is a registry key that points at the documentation if it was installed, which would be the best approach for IDLE to use).
The makefiles don't urgently need to remove those references. If people still want to build it, they're welcome to [try]. It gives people with their own build processes a chance to adapt - we can remove it all later.
zooba commentedon Mar 22, 2022
For the registry key, reading the default value from key "HKCU\Software\Python\PythonCore\{sys.winver}\Help\Main Python Documentation" (or HKLM - no need to worry about the Wow6432Node bit here) and passing it to os.startfile() will work for all active releases.
If the key is missing, so are the local docs, so falling back to the web docs is a fine option.
zooba commentedon Mar 22, 2022
The key is defined at https://github.com/python/cpython/blob/main/Tools/msi/doc/doc.wxs#L17 and is not set for a Store install at all. But we don't include the docs in that either - go straight to the web.
eryksun commentedon Mar 22, 2022
Do you have any thoughts about distributing the docs in ePub format?
ned-deily commentedon Mar 22, 2022
At a minimum, though, Doc/tools/templates/download.html should be changed to remove the chm reference.
zooba commentedon Mar 22, 2022
If Windows includes a reader for all supported versions, and it's easy
to build, sure. But I don't think the first bit is true.
Most people are going to be fairly comfortable with their default
browser, and many are going to greatly prefer it. I think loose HTML
files is a good option from every POV other than being a large number of
loose files.
2 remaining items
zooba commentedon Mar 23, 2022
This should work for you (luckily, this is about the simplest possible case):
zooba commentedon Mar 23, 2022
New changeset fe01060 by Steve Dower in branch 'main':
bpo-47086: Remove dead link to old CHM documentation (GH-32075)
fe01060
pythongh-95841: IDLE - Revise Windows local doc url
gh-95841: IDLE - Revise Windows local doc url (#95845)
pythongh-95841: IDLE - Revise Windows local doc url (pythonGH-95845)
pythongh-95841: IDLE - Revise Windows local doc url (pythonGH-95845)
gh-95841: IDLE - Revise Windows local doc url (GH-95845)
gh-95841: IDLE - Revise Windows local doc url (GH-95845) (#95905)
kilitary commentedon Dec 4, 2023
CHM is totally removed? It is very good at search and fast navigating, rather than render all the documentation tree.
It would be good if user can compile it for itself, because this format is very handy over browser.
zooba commentedon Dec 5, 2023
People can still compile the CHM themselves - use
Doc\make.bat htmlhelp- though we aren't accepting fixes specifically for it anymore (e.g. to fix crashes due to unsupported characters in the index).pythongh-91242: Remove CHM (Compiled HTML Help) build infrastructure