WSL: Chrome on Windows does not find the `_static` style in built HTML doc

[mkoeppe]

In the parts of the reference manual, _static is a symlink to ../_static. Browsers running in Windows (tested with Chrome) cannot resolve the symlink, so the furo style is not applied.

Replacing the symlink by a copy of the directory is a workaround for this problem; but there also remains a problem loading mathjax in this configuration.

[mkoeppe]

Related to discussion in #31415 @tobiasdiez @kwankyu @haraldschilly

[haraldschilly]

Not sure why I'm mentioned. For the online doc files, which are served via a CDN that doesn't read symlinks as well, there is a small routine to fix it by changing the html output. Sounds like this is the same or at least very similar.

[kwankyu]

Right. The small routine replaces every mention of the symlink "_static" in html files to the target of the symlink. Thus the routine takes a while to do its work.

For example, the routine converts the line in local/share/doc/sage/html/en/reference/schemes/index.html

 <link rel="stylesheet" type="text/css" href="_static/pygments.css" />     

to

 <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />     

So the html files treated by the routine does not use the symlink.

Perhaps the same routine could be used to fix the problem on windows.

Then why do we use the symlink in the first place? This is hard-wired in how sphinx works (the static files should be in a directory in the root). Perhaps we cannot change this.

[kwankyu]

By the way, @haraldschilly, please consider https://github.com/sagemath/documentation/pull/27 for your next release. (test first)

[haraldschilly]

By the way, @haraldschilly, please consider sagemath/documentation#27 for your next release. (test first)

Oh, I certainly forgot about it, thx for reminding me. Let's see how well this works with the next release :+1:

[mkoeppe]

Perhaps the same routine could be used to fix the problem on windows.

Yes! +1 to just build this into our scripts.

[mkoeppe]

why do we use the symlink in the first place? This is hard-wired in how sphinx works (the static files should be in a directory in the root). Perhaps we cannot change this.

It looks to me like the whole symlinking business comes from sage_docbuild, not sphinx. See https://github.com/sagemath/sage/blob/develop/src/sage_docbuild/ext/multidocs.py#L292

[kwankyu]

Yes, the symlinking business is done in sage_docbuild. It does that because, I believe, sphinx expects to find the static directory at the root of the target files, and we do not want to copy the static directory into every root directory of the component documents (each chapter of the reference manual), and hence we writes the symlinks instead.

I meant that we must stick to the way how sphinx deals with the static files.

[kwankyu]

In the parts of the reference manual, _static is a symlink to ../_static. Browsers running in Windows (tested with Chrome) cannot resolve the symlink, so the furo style is not applied.

What browser is this? Edge on Windows 10 seems to work fine... (Actually, the Windows is a virtual machine, and I opened the reference manual in the host machine (mac) from the Edge running in the virtual machine)

[kwankyu]

I also tried with Chrome in the same setting. No problem either.

[mkoeppe]

This might be a difference between WSL 1 and 2

[kwankyu]

My virtual machine is VMware. So is it difference between VMware and WSL?

[kwankyu]

Perhaps VMware resolves the symlinks so that Windows does not see the symlinks... But Windows explorer sees the symlinks (and fail to open).

[kwankyu]

This seems related: https://github.com/microsoft/WSL/issues/5118

Then it is a problem of WSL?

[mkoeppe]

I meant that we must stick to the way how sphinx deals with the static files.

I agree, this does not seem to be configurable in Sphinx.

So we'll have to run the HTML fixup routine somewhere. https://github.com/sagemath/sage/blob/develop/src/sage_docbuild/builders.py#L173 looks like a place that could work

[kwankyu]

Yes.

The fixup will take some time. So, perhaps, it should run only if self.name == 'website':

[kwankyu]

The routine in the PR mentioned above (perhaps slightly changed from Harald's) is

# -------------------------------------------------------------------
# remove `_static` symbolic links and resolve the links in html files
# -------------------------------------------------------------------

log.info('### Remove symlinks to Sphinx _static directories')

def links():
    for d in ['html', 'pdf']:
        ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), d))
        files_cmd = sp.Popen(f"find {ROOT} -type l -name _static".split(), stdout=sp.PIPE)
        for link in files_cmd.stdout:
            yield link

for link in links():
    link = link.decode('utf8').strip()
    path = os.path.dirname(link)
    target = os.readlink(link)

    log.info(f"Resolving _static to {target} in subdirectories of {path}")
    os.system(r'find %s -type f -name "*.html" -exec sed -i '' -e "s/_static/%s/" {} \;' % (path, target.replace('/', r'\/')))

    log.info(f"Removing symbolic link {link}")
    os.unlink(link)

This may be rewritten more pythonic...

[mkoeppe]

In incremental docbuilds, one can probably save a bit of time by using find .... -newer reference-file to filter out files that have already been processed previously