Documentation links missing

[pett]

In the 1.5 release, clicking on Help→Programming Manual, then "API Reference", then "Python Classes" produces a list of classes and short descriptions. Those class names are links that go to pages that describe them in greater detail. In the current daily build they are not links -- they are just bold text.

[Zach Pearson]

On it, I was able to see the problem in today's build too. I checked readthedocs builds and they're failing at the last step with Sphinx trying to import stuff from cage_builder. Doing a local build to see what happens.

[Zach Pearson]

Let's see if the fixes that made ReadtheDocs work again also make tomorrow's daily build work. I wish I could guarantee it, but documentation works for local builds.

[pett]

Fingers crossed! :-)

[pett]

Are your fixes on the develop branch? When I try to "make install" in docs I get various errors, such as:

# 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 /Users/pett/src/chimerax/ChimeraX.app/Contents/lib/python3.9/site-packages ]; then \

ln -s /Users/pett/src/chimerax/ChimeraX.app/Contents/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages/chimerax chimerax ; \
INTERNAL_CHIMERAX=1 /Users/pett/src/chimerax/utils/doc_symlinks.sh ; \

fi

/Users/pett/src/chimerax/utils/doc_symlinks.sh: line 4: realpath: command not found
/Users/pett/src/chimerax/utils/doc_symlinks.sh: line 9: mapfile: command not found
/Users/pett/src/chimerax/utils/doc_symlinks.sh: line 10: mapfile: command not found
/Users/pett/src/chimerax/utils/doc_symlinks.sh: line 11: mapfile: command not found
ln: docs/devel/: No such file or directory
mkdir: /docs/devel: No such file or directory
/Users/pett/src/chimerax/utils/doc_symlinks.sh: line 37: cd: /docs/devel/modules: No such file or directory
/Users/pett/src/chimerax/ChimeraX.app/Contents/bin/python3.9 -I /Users/pett/src/chimerax/ChimeraX.app/Contents/Library/Frameworks/Python.framework/Versions/3.9/bin/sphinx-build -b html -d _build/doctrees . _build/html
find: src/bundles: No such file or directory
find: src/bundles//docs: No such file or directory
find: src/bundles//docs: No such file or directory

[pett]

I don't think essex2 has those commands either.

[Zach Pearson]

It looks like mapfile is a builtin of Bash 4 (released around 2009). essex2 has 3.2.

realpath is one of the GNU coreutils which can be installed on macs with homebrew but comes with Ventura at /bin/realpath

I can look for workarounds for each of them, but the path of least resistance is brew update && brew upgrade && brew install bash coreutils

[pett]

Installing those via brew did get my documentation build to work, and the links active. The daily build is still not showing links for the classes and looking at the output I see that essex2 is having the exact same problems with "realpath" and "mapfile". I'm brew-installing those on essex2 and we'll see if that makes things better tomorrow -- but I dunno, brew's bash is in /usr/local/bin, so will it find that before /bin? Also, brew installed realpath as grealpath.

Would be nice to have a better way to notice that building the documentation has failures.

[goddard@…]

I hope the builds for everyone else on Macs don't require installing new tools now.  In the past it only needed Xcode and if we want to encourage outside developers down the road we should keep it that way.

[pett]

The class names continue to not be links in today's build. Looking at the output it seems that it was okay that realpath was named grealpath, but "mapfile" continues to not be found, undoubtedly because the bash that supports that is /usr/local/bin/bash rather than /bin/bash.

[pett]

Still no links in today's build.

[Zach Pearson]

I made the default bash for the chimera account /usr/local/bin/bash, which is version 5.2 -- released last year, vs. 3.2 which was released in 2006. I then fired off a build, which was successful.

if [ -d /Users/chimera/src/ChimeraX/ChimeraX.app/Contents/lib/python3.9/site-packages ]; then \
		ln -s /Users/chimera/src/ChimeraX/ChimeraX.app/Contents/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages/chimerax chimerax ; \
		INTERNAL_CHIMERAX=1 /Users/chimera/src/ChimeraX/utils/doc_symlinks.sh ; \
	fi
/Users/chimera/src/ChimeraX/ChimeraX.app/Contents/bin/python3.9 -I /Users/chimera/src/ChimeraX/ChimeraX.app/Contents/Library/Frameworks/Python.framework/Versions/3.9/bin/sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v5.1.1
making output directory... done

Should work tomorrow.

[pett]

The daily build continues to have bold text instead of links, likely because euclid, the ARM build machine, has the same problems with mapfile and realpath.

[Zach Pearson]

I installed coreutils and bash 5.2 on euclid, then fired off a build, which was again successful with the same output as above.

Frustratingly, the links are still just bold text. I checked today's build results; for some reason the chimera account on euclid did not find realpath or the new bash.

[Zach Pearson]

I made sure that /opt/homebrew/bin was on the path for whatever environment "ssh chimera@… bash" (from the nightly script) conjures, so this should finally start working tomorrow.

[Zach Pearson]

Documentation links are working again as of today's daily build.