Windows v3.10.3 .chm file (in python310\doc) page headings are messed up and spread out over several lines. Also the font has changed from the former san serif font to a smaller and harder to read serif font.

[DonnieODonnell]

BPO	47051
Nosy	@pfmoore, @tjguk, @zware, @zooba, @DonnieODonnell

^{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 = None
closed_at = None
created_at = <Date 2022-03-17.20:39:27.706>
labels = ['type-bug', '3.10', 'OS-windows', 'docs']
title = 'Windows v3.10.3 .chm file (in python310\\doc) page headings are messed up and spread out over several lines. Also the font has changed from the former san serif font to a smaller and harder to read serif font.'
updated_at = <Date 2022-03-21.23:07:21.078>
user = 'https://github.com/DonnieODonnell'

bugs.python.org fields:

activity = <Date 2022-03-21.23:07:21.078>
actor = 'steve.dower'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Windows']
creation = <Date 2022-03-17.20:39:27.706>
creator = 'DonnieODonnell'
dependencies = []
files = []
hgrepos = []
issue_num = 47051
keywords = []
message_count = 2.0
messages = ['415688', '415723']
nosy_count = 6.0
nosy_names = ['paul.moore', 'tim.golden', 'docs@python', 'zach.ware', 'steve.dower', 'DonnieODonnell']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue47051'
versions = ['Python 3.10']

[zooba]

I guess for 3.11 we should just switch to loose HTML files and using the default browser, rather than fighting with dead CHM tools.

No idea what may have caused this. Has anyone tried analysing the file for unsupported JavaScript or something? I think that's what caused it last time. Maybe Sphinx got an update and is using unsupported CSS?

[zooba]

Doesn't seem to be any relevant changes in the repo between v3.10.2 and v3.10.3, and the theme hasn't changed. Obviously the HTMLHelp tools haven't changed in a decade or so, and the only difference in the build logs looks like less errors in the later one (apparently index terms didn't get fixed up properly in 3.10.2).

So other than running the build again and hoping (which we'll likely be doing later this week anyway), doesn't seem to be anything that can be fixed here.

[panda-34]

The problem is caused by this change:
in 3.10.2:
<link rel="stylesheet" href="_static/pydoctheme.css" type="text/css" />
in 3.10.3:
<link rel="stylesheet" href="_static/pydoctheme.css?2022.1" type="text/css" />

[zooba]

Well spotted! If someone figures out where that's coming from, we can definitely backport a fix so that the next round of 3.9 and 3.10 updates have working docs (the CHM is already gone for 3.11, so it doesn't matter there).

[CAM-Gerlach]

If someone figures out where that's coming from, we can definitely backport a fix so that the next round of 3.9 and 3.10 updates have working docs (the CHM is already gone for 3.11, so it doesn't matter there).

The python-docs-theme, specifically here.

The fingerprinting was added in python/python-docs-theme/pull/79 , to fix the caching issue in python/python-docs-theme#78 . However, it could be disabled in the conf.py here, though that would mean potentially regressing on the caching issue for the online docs that the vast majority of people use.

The 3.9 branch is built, so it might be stuck with it absent special provisions to fix this.

@JulienPalard any thoughts here?

[zooba]

We should be able to conditionally disable it when the target is htmlhelp, right?

[CAM-Gerlach]

Oh yeah, of course, since its a theme setting and conf.py is dynamic—I somehow didn't think of that. We could check if "htmlhelp" in sys.argv (not sure if there's a better way to detect the builder in conf.py without registering a hook to modify the config after parsing, since AFAIK sys.argv is not parsed at that point) and only set stylesheet to the un-fingerprinted pydoctheme.css if so.

I could go ahead with that, unless anyone else has a better idea?

[zooba]

It looks like at least the standard docs build passes it as -bhtmlhelp (appears as -b%1 in make.bat), so you might need a slightly more involved check, but if we haven't got access to a parsed set of args then that's the best we can do.

[CAM-Gerlach]

Good catch. It only ended up being a fraction more complicated, any('htmlhelp' in arg for arg in sys.argv). PR opened as #95556 ; it seems to produce the intended result in the built files but I cannot confirm it in an actual Windows HTML help viewer. @zooba or someone else here, do you think you could check? Thanks!

[zooba]

Thanks for the fix, I checked and it works fine.

We probably ought to forward port it as well, since the build script is still there. But maybe there's a better hack we could use instead? Maybe an explicit option or env var for it?

[CAM-Gerlach]

We probably ought to forward port it as well, since the build script is still there.

Not sure if you mean the conf.py configuration file, the htmlhelp stub in the Makefile (which could be removed) or something else I'm not aware of. If you think people are still using the ancient htmlhelp builder, I suppose we could—I can submit a PR if you want, up to you.

But maybe there's a better hack we could use instead? Maybe an explicit option or env var for it?

Unless there's some way to get legacy Windows Help to ignore a ? finger print in the stylesheet path that we would be able to affect from Python (which is well outside my expertise), I'm not sure exactly what you mean by "it" here—we are using an explicit option in the conf.py to set the stylesheet path.

Instead of parsing sys.argv and then setting the option directly, we could do something like the following in the conf.py or in e.g. escape4chm.py:

def hardcode_stylesheet_htmlhelp(app):
    if getattr(app.builder, 'name', None) == 'htmlhelp':
        app.env.config.html_style = 'pydoctheme.css'

def setup(app):
    app.connect('builder-inited', hardcode_stylesheet_htmlhelp)

Assuming that works, but it adds complexity to support a fairly obsolete use can and there isn't a practical benefit over the existing two-liner.

The main thing that would be ideal to avoid is hardcoding the name of the stylesheet from the theme, as opposed to reading the existing value, stripping the fingerprint and setting that instead, but at least poking around with Sphinx I couldn't find a way to easily retrieve the theme config, short of truly awful hacks like importing the theme module, getting its __file__, reading the theme.ini there, extracting the stylesheet and then stripping the fingerprint and setting it again. This only is even a theoretical problem on future versions of the docs where the theme stylesheet changes its name, so keeping the hack limited to the 3.10 config file avoids that risk.

[zooba]

The build script is the path in make.bat that allows it to run. Since we know it won't work without the fix, we should probably make it fail to build entirely on 3.11+ - or add the conf.py fix to the newer branches.

I agree that the current fix is just as good as the longer one you proposed, so let's just forward port it to newer versions. Maybe we can also print out a "CHM is no longer supported - may be removed in future" message?

[CAM-Gerlach]

I agree that the current fix is just as good as the longer one you proposed, so let's just forward port it to newer versions. Maybe we can also print out a "CHM is no longer supported - may be removed in future" message?

Thanks, opened #95607 with those changes as requested 👍

[zooba]

Awesome. Glad to close this one (though also happy to have moved on from CHM already)

[CAM-Gerlach]

Thanks for guiding this along, @zooba !