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

@pradyunsg

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

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

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

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

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')

Consider reporting that to pydata-sphinx-theme?

@story645

~~@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

@AA-Turner

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

Done in 44a7820, thank you for the suggestion.

A

Awesome, thanks for the quick change! :)

Navigation Menu

Repository navigation

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

Describe the bug

How to Reproduce

Environment Information

Sphinx extensions

Additional context

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

Description

Describe the bug

How to Reproduce

Environment Information

Sphinx extensions

Additional context

Activity

AA-Turner commented on Jul 26, 2023

henryiii commented on Jul 26, 2023

pradyunsg commented on Jul 26, 2023

story645 commented on Aug 10, 2023

pradyunsg commented on Aug 10, 2023

AA-Turner commented on Aug 11, 2023

pradyunsg commented on Aug 11, 2023

AA-Turner commented on Aug 11, 2023

pradyunsg commented on Aug 12, 2023

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions