Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include HTML docs with Windows installer instead of CHM #91242

Closed
zooba opened this issue Mar 21, 2022 · 16 comments
Closed

Include HTML docs with Windows installer instead of CHM #91242

zooba opened this issue Mar 21, 2022 · 16 comments
Assignees
Labels
3.11 bug and security fixes OS-windows type-feature A feature request or enhancement

Comments

@zooba
Copy link
Member

zooba commented Mar 21, 2022

BPO 47086
Nosy @terryjreedy, @pfmoore, @tjguk, @ned-deily, @zware, @zooba, @JulienPalard
PRs
  • bpo-47086: Remove .chm from Windows installer and add HTML docs #32038
  • bpo-47086: Remove dead link to old CHM documentation #32075
  • 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']

    @zooba
    Copy link
    Member Author

    zooba commented 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 zooba added 3.11 bug and security fixes OS-windows type-feature A feature request or enhancement labels Mar 21, 2022
    @zooba
    Copy link
    Member Author

    zooba commented 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
    Copy link
    Member Author

    zooba commented 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
    Copy link
    Member

    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
    Copy link
    Member Author

    zooba commented 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
    Copy link
    Member Author

    zooba commented 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
    Copy link
    Member Author

    zooba commented 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
    Copy link
    Contributor

    eryksun commented Mar 22, 2022

    Do you have any thoughts about distributing the docs in ePub format?

    @ned-deily
    Copy link
    Member

    At a minimum, though, Doc/tools/templates/download.html should be changed to remove the chm reference.

    @zooba
    Copy link
    Member Author

    zooba commented Mar 22, 2022

    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.

    @ned-deily
    Copy link
    Member

    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.

    @terryjreedy
    Copy link
    Member

    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 python.org/...(but '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.

    @zooba
    Copy link
    Member Author

    zooba commented Mar 23, 2022

    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"
        try:
            return winreg.QueryValue(winreg.HKEY_CURRENT_USER, KEY)
        except FileNotFoundError:
            pass
        try:
            return winreg.QueryValue(winreg.HKEY_LOCAL_MACHINE, KEY)
        except FileNotFoundError:
            pass
        return f"https://docs.python.org/{sys.version_info.major}.{sys.version_info.minor}/"

    @zooba
    Copy link
    Member Author

    zooba commented Mar 23, 2022

    New changeset fe01060 by Steve Dower in branch 'main':
    bpo-47086: Remove dead link to old CHM documentation (GH-32075)
    fe01060

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @zooba zooba closed this as completed Jul 17, 2022
    terryjreedy added a commit to terryjreedy/cpython that referenced this issue Aug 10, 2022
    python#91242 replaced the Windows chm help file with a copy
    of the html docs.  This PR replaces the IDLE code that
    fetches the Windows local help url passed to os.startfile.
    terryjreedy added a commit that referenced this issue Aug 11, 2022
    #91242 replaced the Windows chm help file with a copy
    of the html docs.  This PR replaces the IDLE code that
    fetches the Windows local help url passed to os.startfile.
    Co-authored-by: Steve Dower
    miss-islington pushed a commit to miss-islington/cpython that referenced this issue Aug 11, 2022
    pythonGH-91242 replaced the Windows chm help file with a copy
    of the html docs.  This PR replaces the IDLE code that
    fetches the Windows local help url passed to os.startfile.
    Co-authored-by: Steve Dower
    (cherry picked from commit bdb2cf8)
    
    Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
    miss-islington pushed a commit to miss-islington/cpython that referenced this issue Aug 11, 2022
    pythonGH-91242 replaced the Windows chm help file with a copy
    of the html docs.  This PR replaces the IDLE code that
    fetches the Windows local help url passed to os.startfile.
    Co-authored-by: Steve Dower
    (cherry picked from commit bdb2cf8)
    
    Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
    miss-islington added a commit that referenced this issue Aug 11, 2022
    GH-91242 replaced the Windows chm help file with a copy
    of the html docs.  This PR replaces the IDLE code that
    fetches the Windows local help url passed to os.startfile.
    Co-authored-by: Steve Dower
    (cherry picked from commit bdb2cf8)
    
    Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
    terryjreedy pushed a commit that referenced this issue Aug 12, 2022
    GH-91242 replaced the Windows chm help file with a copy
    of the html docs.  This PR replaces the IDLE code that
    fetches the Windows local help url passed to os.startfile.
    
    Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
    Co-authored-by: Steve Dower
    Approved by Steve Dower, #95845 (review), 2nd subblock.
    
    (cherry picked from commit bdb2cf8)
    @kilitary
    Copy link

    kilitary commented 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
    Copy link
    Member Author

    zooba commented 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).

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.11 bug and security fixes OS-windows type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    5 participants