Missing parts of Mac/Windows programming documentation

[Eric Pettersen]

Comparing the builtin non-Linux documentation for Python modules (help:devel/modules.html) to the online equivalent (​https://www.cgl.ucsf.edu/chimerax/docs/devel/modules.html) shows that the builtin one is missing all the bullet-list hyperlinks (rendering the page useless). This problem is undoubtedly due to these kinds of errors in the documentation installation:

/Users/pett/src/chimerax/docs/devel/data_interface.rst:43: WARNING: toctree contains reference to nonexisting document 'modules/core/commands/commands'

It would be nice if this worked for the 1.7 release, but if it is in the least bit non-trivial it should probably just go in 1.8.

[Zach Pearson]

Shouldn't be too hard to sneak into 1.7, it's just shuffling data around to the right location when we build documentation.

[Zach Pearson]

Do you have the core installed in editable mode? I don't get that error when I build the documentation, but I do get errors about mmcif not being able to find things from mmcif_cpp

[Eric Pettersen]

No, I don't have it installed in editable mode. I mean, it doesn't *just* fail in my personal build, it's failing in the distributed builds too.

[Eric Pettersen]

Do you already have symbolic links in docs/devel/modules? I don't have any and "make install" in docs doesn't make any. If you already have links there, that might be why things work for you.

[Zach Pearson]

I don't already have them, they get regenerated when I make -C docs install

[Eric Pettersen]

If I do that (rather then "make install" directly in the docs directory) then the links get made for me too and things work. Now it is just a question of getting the distribution builds to do that...

[Zach Pearson]

Looking at the build log for the Mac version from last night, there are errors when running utils/doc_symlinks.sh that state the shell can't find the mapfile command. mapfile is a bash built-in from bash >= 4.0, so my guess is the issue is that bash on those machines is too old.

[Eric Pettersen]

From ​https://www.computerhope.com/unix/bash/mapfile.htm:

The mapfile command is not very portable. That is, if you want to ensure your script can run on a wide array of systems, it's not recommended to use mapfile. It's provided primarily as a convenience. The same functionality can be achieved using a read loop, although in general mapfile performs faster.

[Zach Pearson]

Upgraded the script to use bash 3 features; docs should work in both the develop and the release branches tomorrow.