This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Include HTML docs with Windows installer instead of CHM
Type: enhancement Stage: patch review
Components: Windows Versions: Python 3.11
Status: open Resolution:
Dependencies: Superseder:
Assigned To: steve.dower Nosy List: mdk, ned.deily, paul.moore, steve.dower, terry.reedy, tim.golden, zach.ware
Priority: normal Keywords: patch

Created on 2022-03-21 20:44 by steve.dower, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 32038 merged steve.dower, 2022-03-21 22:11
PR 32075 merged steve.dower, 2022-03-23 11:56
Messages (14)
msg415701 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-21 20:44
CHM is getting too hard to handle (see e.g. issue47051 for the latest issue), so let's just bite the bullet and ship the HTML docs instead.
msg415735 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-22 01:09
New changeset 3751b6b030b4a3b88959b4f3c4ef2e58d325e497 by Steve Dower in branch 'main':
bpo-47086: Remove .chm from Windows installer and add HTML docs (GH-32038)
msg415736 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-22 01:09
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.
msg415819 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-22 21:35
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/

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.)
msg415822 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-22 22:03
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.
msg415824 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-22 22:06
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.
msg415825 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-22 22:07
The key is defined at 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.
msg415827 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2022-03-22 22:15
Do you have any thoughts about distributing the docs in ePub format?
msg415828 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-22 22:20
At a minimum, though, Doc/tools/templates/download.html should be changed to remove the chm reference.
msg415829 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-22 22:20
> Do you have any thoughts about distributing the docs in ePub format?

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.
msg415830 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2022-03-22 22:23
> Do you have any thoughts about distributing the docs in ePub format?

Note that it's *much* easier to manufacture the docs in html format than it is in ePub format.
msg415848 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2022-03-23 01:54
In the IDLE Help menu, 'Python Docs', default hotkey 'F1', invokes '<<python-docs>>', which is handled by EditorWindow.help_docs.  For Windows, line 599, is 'os.startfile(self.help_url)'.  (Otherwise, webbrowser is used.)  On Windows, help_url is os.path.join(sys.base_prefix, 'Doc','Python%s.chm' % _sphinx_version())
if the result is valid, else '3.1' because only 3 chars are grabbed).

How do I use winreg to get the file name from
"HKCU\Software\Python\PythonCore\{sys.winver}\Help\Main Python Documentation"?
The winreg doc assumes some knowledge of registry terminology that I do not have and has no examples, so my attempts failed.
msg415866 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-23 11:54
This should work for you (luckily, this is about the simplest possible case):

import sys
import winreg

def get_help():
    KEY = rf"Software\Python\PythonCore\{sys.winver}\Help\Main Python Documentation"
        return winreg.QueryValue(winreg.HKEY_CURRENT_USER, KEY)
    except FileNotFoundError:
        return winreg.QueryValue(winreg.HKEY_LOCAL_MACHINE, KEY)
    except FileNotFoundError:
    return f"{sys.version_info.major}.{sys.version_info.minor}/"
msg415884 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-23 16:14
New changeset fe010605f87f988ef1053e372d1c3898d2633d96 by Steve Dower in branch 'main':
bpo-47086: Remove dead link to old CHM documentation (GH-32075)
Date User Action Args
2022-04-11 14:59:57adminsetgithub: 91242
2022-03-23 16:14:17steve.dowersetmessages: + msg415884
2022-03-23 11:56:41steve.dowersetstage: commit review -> patch review
pull_requests: + pull_request30163
2022-03-23 11:54:05steve.dowersetmessages: + msg415866
2022-03-23 01:54:33terry.reedysetmessages: + msg415848
2022-03-22 22:50:57eryksunsetnosy: - eryksun
2022-03-22 22:23:21ned.deilysetmessages: + msg415830
2022-03-22 22:20:58steve.dowersetmessages: + msg415829
2022-03-22 22:20:11ned.deilysetmessages: + msg415828
2022-03-22 22:15:39eryksunsetnosy: + eryksun
messages: + msg415827
2022-03-22 22:07:27steve.dowersetmessages: + msg415825
2022-03-22 22:06:41steve.dowersetmessages: + msg415824
2022-03-22 22:03:46steve.dowersetmessages: + msg415822
2022-03-22 21:35:06ned.deilysetnosy: + terry.reedy, ned.deily, mdk
messages: + msg415819
2022-03-22 01:09:56steve.dowersetassignee: steve.dower
messages: + msg415736
stage: patch review -> commit review
2022-03-22 01:09:02steve.dowersetmessages: + msg415735
2022-03-21 22:11:45steve.dowersetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request30128
2022-03-21 20:44:27steve.dowercreate