search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.45k stars 2.1k forks source link

HTMLHELP Relative URL strings must not have a query component #11889

Closed mkay-sh closed 6 months ago

mkay-sh commented 8 months ago

Describe the bug

With the implementation of #11415 checksums are added to css file links in the html output. But in the htmlhelp output format the windows help viewer fails to load the stylesheets. If I remove the query component before compiling the chm file it works.

How to Reproduce

  1. Use any sphinx project and run it with the output format htmlhelp.
  2. Compile the .hpp file with the Microsoft HTML HELP Workshop.
  3. Open the chm file and there are no styles.

Environment Information

Platform:              win32; (Windows-11-10.0.22631-SP0)
Python version:        3.12.1 (tags/v3.12.1:2305ca5, Dec  7 2023, 22:03:25) [MSC v.1937 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.20.1
Jinja2 version:        3.1.3
Pygments version:      2.17.2

Additional context

It's a similar issue to #11598 where it does not work with epub. I can provide a pull request to fix this if you are interested.

AA-Turner commented 8 months ago

Hi @mkay-sh,

A PR would be appreciated, thank you!

A

jayaddison commented 8 months ago

Do you have any notes about the introduction of the CRC32 checksums @AA-Turner? I'm guessing it may have been to help cache-bust CSS/JS retrieval?

AA-Turner commented 8 months ago

For exactly that reason, yes.

A

jayaddison commented 8 months ago

Ok - and is/was it not possible to use <filename>.<checksum>.css as a filename format instead of emitting <filename>.css?<checksum>-format URIs? (there are no doubt other downsides to embedding the checksum in the filename that I'm not thinking of, but it seems like a possible alternative)

jayaddison commented 8 months ago

(my honest opinion is that I feel like this should be solved by ETags (for content caching) and subresource integrity (content integrity validation) - but I don't know how reliable those are at scale, especially for legacy/speciality user agents)