Opened 3 years ago

Last modified 3 years ago

#25089 new defect

Cygwin: static resources for HTML docs missing

Reported by: embray Owned by:
Priority: major Milestone: sage-pending
Component: porting: Cygwin Keywords: docbuild
Cc: Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:


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.

Change History (3)

comment:1 Changed 3 years ago by embray

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.

comment:2 Changed 3 years ago by slelievre

See possibly related discussion at #25111.

comment:3 Changed 3 years ago by embray

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.

Note: See TracTickets for help on using tickets.