add_css_file return wrong URI when dealing with local files on windows platform

[12rambau]

Describe the bug

I'm copying some css and js files from my local lib. Everything works fine with my Linux build but it fails when trying to make it run on windows platform.

How to Reproduce

the failing test are part of the sphinx-contrib/icon repository. The latest build can be found here: https://github.com/sphinx-contrib/icon/actions/runs/9315532969/job/25641896049?pr=33

In short my lib is adding few css and js to the app like this:

def setup(app: Sphinx) -> Dict[str, Any]:
    """Add icon node to the sphinx builder."""
    # load the icon node/role
    app.add_node(icon_node, **_NODE_VISITORS)  # type: ignore
    app.add_role("icon", Icon())

    # load the font
    font_handler = Fontawesome()

    # install html related files
    app.add_css_file(str(font_handler.css_file.resolve()))
    app.add_js_file(str(font_handler.js_file.resolve()))

    # install latex files
    app.add_latex_package("fontspec")
    app.connect("config-inited", font_handler.add_latex_font)
    app.connect("config-inited", font_handler.enforce_xelatex)
    app.connect("builder-inited", font_handler.add_latex_font_files)

    return {
        "version": __version__,
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }

And the error I get when the build runs on windows is the following:

 OSError: [Errno 22] Invalid argument: 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\pytest-of-runneradmin\\pytest-0\\fa6-icon\\_build\\html\\_static\\D:\\a\\icon\\icon\\sphinxcontrib\\icon\\node_modules\\@fortawesome\\fontawesome-free\\css\\all.min.css'

My guess is that add_css_file is not catching windows based absolute path the D: should not be here.

Environment Information

I don't own a windows machine myself so the report i'm sending is the one from a linux based codespace. I think it won't be relevant:

Platform:              linux; (Linux-6.5.0-1021-azure-x86_64-with-glibc2.31)
Python version:        3.10.13 (main, May 14 2024, 22:40:16) [GCC 9.4.0])
Python implementation: CPython
Sphinx version:        7.3.7
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

[sphinxcontrib.icon]

[electric-coder]

You're getting the error when running pytest? That's what the path suggests:

\pytest-of-runneradmin\\pytest-0

There were some recent changes to the way Sphinx's pytests are organized but it's strange that a build fails with a pytest path.

I don't own a windows machine myself

FYI, that base path is where pytest stores temporary files by default on Windows.

[12rambau]

the complete workflow is nox build the test environment in a venv and then pytest is run within this environment to test if the behaviours of the lib.

why would pytest copy all these files to a temp environment ? Is it because I'm using the "sphinx.testing.fixtures" in my conftext to build minimal documentations ?

[electric-coder]

why would pytest copy all these files to a temp environment ?

Assuming you're running sphinx-build -b html <sourcedir> tmp_path inside a test with tmp_path being a pytest fixture I'd recommend putting a breakpoint on app.add_css_file(str(font_handler.css_file.resolve())) to check just what .resolve() returns there. I'm not sure if calling Sphinx.add_css_file is what causes the static files to be copied to Sphinx's build <outputdir> but you should check that the path is correct and the files are getting copied. Without using a debugger it's guesswork, but I'm guessing there's a diference between how Linux and Windows resolve the paths at that line and that's the cause of the problem, likely not a Sphinx issue per se.

[12rambau]

The fact that everything is performed in the CI/CD environment is making it difficult to debug but thanks for the headstart I'll try to write this to an artifact file and check exactly what is happening there.

The fact that the add_css_file function is relying on a str instead of a path object makes me think it can be broken easily by platform specific differences:

sphinx/sphinx/builders/html/__init__.py

Line 328 in 53c31f7

def add_css_file(self, filename: str, **kwargs: Any) -> None:

I'll continue investigating and close the issue if it's not related to Sphinx.

[picnixz]

Isn't it the same as #11860? It might also be related to #10910.

[12rambau]

I think I effectively duplicated myself. That's sad. on the other hand this one got much traction ;-) I'll close #11860.

I think the bug reported in #10910 is exactly the source of the issue.