Windows build fails due to symbolic link docs/devel/apps

[Tom Goddard]

Building ChimeraX on Windows 11 (vizvault.cgl.ucsf.edu) fails apparently because it cannot access

docs/devel/apps/ChimeraX/ChimeraX-icon.svg

because docs/devel/apps is a symbolic link. The link is correct but I am guessing that the symbolic link handling on Windows is flakey so the sphinx code fails to follow it.

make -C devel install
make[3]: Entering directory '/home/goddard/ucsf/chimerax/docs/devel'
rm -rf _build/* conf.py index.rst _static/cxlinks.js pycache _static/devdocs.css \

apps chimerax modules

sed -e 's/PYTHON_VERSION/3.11/' \

-e 's/CHIMERAX_VERSION/1.10/' \
-e 's/CHX_FULL_VERSION/1.10/' \
< conf.py.in > conf.py

sed '/===/d' /home/goddard/ucsf/chimerax/copyright.txt | \

sed $'/COPYRIGHT_NOTICE/{r /dev/stdin\nd\n}' \
index.rst.in > index.rst

mkdir -p _static
cp ../js/cxlinks.js _static/cxlinks.js
cp ../css/devdocs.css _static/devdocs.css
# This code path handles a built ChimeraX, for the Plato build
# system or on a user's local machine. On readthedocs, the
# symlinks are made in Makefile.readthedocs
if [ -d /home/goddard/ucsf/chimerax/ChimeraX.app/bin/Lib/site-packages ]; then \

ln -s /home/goddard/ucsf/chimerax/ChimeraX.app/bin/Lib/site-packages/chimerax chimerax ; \
INTERNAL_CHIMERAX=1 /home/goddard/ucsf/chimerax/utils/build/doc_symlinks.sh ; \

fi
/home/goddard/ucsf/chimerax/ChimeraX.app/bin/python.exe -I 'C:/cygwin64/home/goddard/ucsf/chimerax/ChimeraX.app/bin/Scripts/sphinx-build.exe' -b html -d _build/doctrees . _build/html
[01mRunning Sphinx v8.2.3[39;49;00m

[01mloading translations [en]... [39;49;00mdone

[01mmaking output directory... [39;49;00mdone

[91mExtension error (sphinx.builders.html)![39;49;00m

Versions

========

• Platform: win32; (Windows-10-10.0.26100-SP0)

• Python version: 3.11.4 (CPython)

• Sphinx version: 8.2.3

• Docutils version: 0.21.2

• Jinja2 version: 3.1.6

• Pygments version: 2.18.0

Last Messages

=============

None.

Loaded Extensions

=================

None.

Traceback

=========

File "C:\cygwin64\home\goddard\ucsf\chimerax\ChimeraX.app\bin\Lib\site-packages\sphinx\events.py", line 415, in emit

raise ExtensionError(

sphinx.errors.ExtensionError: Handler <function validate_html_logo at 0x0000023AB7B84900> for event 'config-inited' threw an exception (exception: 1920 The file cannot be accessed by the system: 'C:
cygwin64
home
goddard
ucsf
chimerax
docs
devel
apps
ChimeraX
ChimeraX-icon.svg')

The full traceback has been saved in:

C:\Users\goddard\AppData\Local\Temp\sphinx-err-1wur_5r5.log

To report this error to the developers, please open an issue at <​https://github.com/sphinx-doc/sphinx/issues/>. Thanks!

Please also report this if it was a user error, so that a better error message can be provided next time.

make[3]: * [Makefile:90: html] Error 2
make[3]: Leaving directory '/home/goddard/ucsf/chimerax/docs/devel'
make[2]: * devel.install Error 2
make[2]: Leaving directory '/home/goddard/ucsf/chimerax/docs'
make[1]: * [Makefile:36: install] Error 2
make[1]: Leaving directory '/home/goddard/ucsf/chimerax'
make: * [Makefile:217: build-from-scratch] Error 2

[Greg Couch]

See ​https://gist.github.com/karlding/7868aac0c54fe94b7ba0a2061e0a4939 for possible fixes. I'd recommend adding "export CYGWIN=winsymlinks:nativestrict" to .bashrc.

[Tom Goddard]

The Windows build does not work on our development machine because of this symbolic link problem. So I think it needs a solution. Our cloud builds apparently work, so there is some magic to make it work. Perhaps Zach can figure out what is needed to make that work.

[Zach Pearson]

Should be fixed as of ​97fa7c. I made it so that instead of trying to get the html_icon through the docs/devel/apps --> $(TOP)/src/apps symbolic link, the variable points to the real relative location of ChimeraX-icon.svg ("../../src/apps/ChimeraX/ChimeraX-icon.svg"). That seemed to fix it the next time I ran 'make -C docs install' from the repo root.

In the future I would move off Cygwin and to Msys2 (what the build runners use). It's got a lot of features over Cygwin, but the one that stands out to me is that you have the pacman package manager from Arch Linux, so you don't have to reinstall the whole thing to change your packages. There's documentation on which packages you need in the programming manual. It (like Cygwin) can also be integrated with the Windows terminal.

[Tom Goddard]

Thanks! Windows build on vizvault now completes successfully for me.