Build Problems with ISIS Docs and -WEBHELP Usage

[KrisBecker]

ISIS version(s) affected: 5.0+ (Perhaps others)

Description
Several problems were discovered when building ISIS documentation. Note that my development environment is as follows:

MacBook Pro (15 inch, 2017)
MacOSX 10.15.3
Xcode 11.3.1

> g++ -v
Configured with: --prefix=/Applications/Xcode.app/Contents/Developer/usr --with-gxx-include-dir=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/4.2.1
Apple clang version 11.0.0 (clang-1100.0.33.17)
Target: x86_64-apple-darwin19.3.0
Thread model: posix
InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

Python 3.6.7 (via Miniconda)
conda 4.9.2

Build Fails on Programmer/Developer Documentation

First, when building the docs (using ninja docs -j7 as per instructions), it issues an error during the generation of the Programmer and Developer documentation. The error generated is show in the following docs build sequence:

warning: Tag 'MSCGEN_PATH' at line 2148 of file '/Users/kbecker/ISIS/Isis4Dev/Repo/ISIS3/build/docBuild/src/docsys/Object/build/Programmer_temp.conf' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: argument 'a4wide' for option PAPER_TYPE is not a valid enum value
Using the default: a4!
sh: dot: command not found
sh: dot: command not found

Essentially, many, many lines of the dot command missing error occurs here and I assume none of the programmer documentation is successfully created.

It looks like the dot program is part of the graphviz package.

-WEBHELP Usage

Then, when attempting to use –web or –webhelp, the following error is thrown:

# In the ISIS installation shell
msi2isis -web
The file /Users/kbecker/miniconda3/envs/isis5eros/doc/Application/presentation/Tabbed/msi2isis/msi2isis.html does not exist.
**PROGRAMMER ERROR** Executing command [open $ISISROOT/doc/Application/presentation/Tabbed/msi2isis/msi2isis.html] failed with return status [256].


# In the build environment
msi2isis -web
The file /Users/kbecker/ISIS/Isis4Dev/Repo/ISIS3/build/doc/Application/presentation/Tabbed/msi2isis/msi2isis.html does not exist.
**PROGRAMMER ERROR** Executing command [open $ISISROOT/doc/Application/presentation/Tabbed/msi2isis/msi2isis.html] failed with return status [256].

This is due to an incorrect path hardcoded in UserInterface.cpp.

How to reproduce

Here are the commands I used for the build:

cd ISIS/Isis4Dev/Repo/ISIS3
conda env create -n isis5eros -f environment.yml
conda activate isis5eros
mkdir build install
cd build
cmake -DisisData=/opt/isis4/data -DisisTestData=/opt/isis4/testData -DJPK2KFLAG=OFF -DCMAKE_BUILD_TYPE=RELEASE -GNinja  ../isis
export ISISROOT=$PWD
export ISISDATA=/opt/isis4/data
ninja install
ninja docs -j7

I am surprised there is no ISIS initialization in there somewhere.

Also, the ./install directory is not used. The ninja install command installs ISIS in $CONDA_PREFIX.

To reproduce the -WEBHELP error:

algebra -web

Possible Solution

I have a PR coming to fix the single line in UserInterface to correct the path. I also added the Graphviz package to both environment YAML files.

Additional context

There is a $CONDA_PREFIX/doc directory that contains other package documentation. However, ISIS documentation is in $CONDA_PREFIX/docs. Seems pretty confusing/inconsistent.

Why not put ISIS document in $CONDA_PREFIX/doc/isis which would also be $ISISROOT/doc/isis/docs in this context.