Cygwin: static resources for HTML docs missing

[embray]

There's a long-standing problem on Cygwin that the built HTML docs don't work correctly locally, because various common static resources (CSS, JS, etc.) can't be found. This is because the Sage multi-doc builder hacks things a bit so that individual sub-docs don't have their own copies of the _static dir, but rather symlink to a common _static dir, presumably to save space on duplicate files.

Unfortunately, this is broken on Windows, since native Windows apps (i.e. the browser) don't understand Cygwin symlinks.

This could be worked around, perhaps, by making hard links instead.

Component: porting: Cygwin

Keywords: docbuild

Issue created by migration from https://trac.sagemath.org/ticket/25089

[embray]

comment:1

In fact it's pretty important that the _static files are not copied into "sub-documents" since the total size of the static files is ~15 MB. So that would result in some signficant blowup.

It should work to make hard links, but that will require a bit of tinkering since currently the symlinks are created when building each sub-document, and the master document hasn't been built yet. Instead, the links should be created while building the master document(s).

Alternatively, perhaps there's some way we can tweak Sphinx to output different relative URLs to the _static directories, and thus create just one at the top level.

[slel]

comment:2

See possibly related discussion at #25111.

[embray]

comment:3

I tried a workaround using hard links but it didn't work because (duh) the way the doc builder currently works, the "sub-documents" are built before the "master document", and those symlinks are made during building of the sub-documents when the master document doesn't exist yet. That works for symlinks, but for hard links the original files should exist in the first place.

I think this could still be fixed be reworking the doc builder so that the _static dirs for sub-documents are only created as part of building the master document.

[mkoeppe]

dup of #35538