Sphinx 7.1 breaks Furo's usage of css_tag(css) on Windows

[henryiii]

Describe the bug

The 7.1.0 release is breaking the Furo theme; css_tag(css) is causing a file to be attempted to be opened with ?digest=e6660623a769aa55fea372102b9bf3151b292993 added to it, which of course breaks.

  File "D:\a\scikit-build-core\scikit-build-core\.nox\docs\Lib\site-packages\furo\theme\furo\base.html", line 62, in block 'regular_styles'
    {{ css_tag(css) }}
  File "D:\a\scikit-build-core\scikit-build-core\.nox\docs\Lib\site-packages\jinja2\sandbox.py", line 393, in call
    return __context.call(__obj, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\a\scikit-build-core\scikit-build-core\.nox\docs\Lib\site-packages\sphinx\builders\html\__init__.py", line 1202, in css_tag
    if checksum := _file_checksum(app.outdir, css.filename):
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\a\scikit-build-core\scikit-build-core\.nox\docs\Lib\site-packages\sphinx\builders\html\__init__.py", line 1254, in _file_checksum
    with open(path.join(outdir, filename), encoding='utf-8') as f:
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OSError: [Errno 22] Invalid argument: 'D:\\a\\scikit-build-core\\scikit-build-core\\docs\\_build\\html\\_static/styles/furo.css?digest=e6660623a769aa55fea372102b9bf3151b292993'

If it's @pradyunsg's Furo's fault, I can open an issue there instead, but this looks like it's an issue with the checksum additions mentioned for 7.1.0? Especially since it only happens on Windows.

Seen in scikit-build/scikit-build-core#440 and scikit-build/scikit-build-core#441.

How to Reproduce

It's hard for me to test, since it's Windows only. Building Scikit-build-core's docs (via nox) on Windows would repeat it. I think any usage of Furo would break it, it doesn't seem to be specific, as it's loading a css file. Maybe other themes that have this construct.

Environment Information

GitHub Actions, windows-latest, with the latest sphinx.

Sphinx extensions

I think it can be done with just a theme.

Additional context

No response

[AA-Turner]

This is a problem with Furo, it seems -- css.filename must be a local file or a URI, and Furo seems to have used a workaround to achieve a similar feature via using an invalid filename (appending the checksum earlier), which Sphinx didn't previously check.

As such I don't think I consider this a breaking change in Sphinx. Sorry not to be more helpful.

A

[henryiii]

Ahh, it must be https://github.com/pradyunsg/furo/blob/f8db95bed5d1c57b4ea6bf536c65560fa9ae33a9/src/furo/__init__.py#L149-L153 then. Thanks! Will open an issue there.

[pradyunsg]

FWIW, it isn't limited to Furo -- at least one more theme is broken by this change. :)

[story645]

Can confirm that I can't build the matplotlib docs anymore either, which means it's also breaking pydata-sphinx, and downgrading to 7.0 removes this error.

OSError: [Errno 22] Invalid argument: 'C:\\Users\\story\\Projects\\matplotlib\\doc\\build\\html\\_static/pygments.css?v3.7.1-2022-g9676e766d4-dirty'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "C:\Users\story\miniconda3\envs\mpl-dev\Lib\site-packages\sphinx\cmd\build.py", line 290, in build_main
    app.build(args.force_all, args.filenames)
  File "C:\Users\story\miniconda3\envs\mpl-dev\Lib\site-packages\sphinx\application.py", line 351, in build
    self.builder.build_update()
  File "C:\Users\story\miniconda3\envs\mpl-dev\Lib\site-packages\sphinx\builders\__init__.py", line 290, in build_update
    self.build(to_build,
  File "C:\Users\story\miniconda3\envs\mpl-dev\Lib\site-packages\sphinx\builders\__init__.py", line 360, in build
    self.write(docnames, list(updated_docnames), method)
  File "C:\Users\story\miniconda3\envs\mpl-dev\Lib\site-packages\sphinx\builders\__init__.py", line 567, in write
    self._write_serial(sorted(docnames))
  File "C:\Users\story\miniconda3\envs\mpl-dev\Lib\site-packages\sphinx\builders\__init__.py", line 577, in _write_serial
    self.write_doc(docname, doctree)
  File "C:\Users\story\miniconda3\envs\mpl-dev\Lib\site-packages\sphinx\builders\html\__init__.py", line 675, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "C:\Users\story\miniconda3\envs\mpl-dev\Lib\site-packages\sphinx\builders\html\__init__.py", line 1105, in handle_page
    raise ThemeError(__("An error happened in rendering the page %s.\nReason: %r") %
sphinx.errors.ThemeError: An error happened in rendering the page api/_api_api.
Reason: OSError(22, 'Invalid argument')

[pradyunsg]

Consider reporting that to pydata-sphinx-theme?

[AA-Turner]

@story645 I can't reproduce that failure, please may you open a new issue or provide the command that you ran?

I managed to reproduce; please see matplotlib/matplotlib#26493 for a proposed fix.

A

[pradyunsg]

@AA-Turner Do you think it's worth improving the error message in this case?

[AA-Turner]

Done in 44a7820, thank you for the suggestion.

A

[pradyunsg]

Awesome, thanks for the quick change! :)