Readthedocs failing

[andrew-platt]

Bug description
There was some kind of update on readthedocs that is now breaking the documentation in the sphinx-build command for html. When 3.4.0 was released (Jan 11) the main branch rendered correctly in rtd (https://readthedocs.org/projects/openfast/builds/19142412/). Today the main branch does not render (https://readthedocs.org/projects/openfast/builds/19323670/) even though nothing has changed in the OpenFAST repository.

The issue that now appears is with the paths used in specifying some locations in the conf.py. The html_extra_path and doxylink variables appear to be set to use the sourcedir instead of builddir. This results in the doxygen directory in build (should be <openfast>/build/docs/../doxygen but gets <openfast>/docs/../doxygen which doesn't exist) and the location of the openfast.tag (should be <openfast>/build/docs/../openfast.tag but looks instead for <openfast>/docs/../openfast.tag).

There were a few packages that are different versions in the new failing build (working --> failing):

• MarkupSafe-2.1.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl --> MarkupSafe-2.1.2-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
• alabaster-0.7.12-py2.py3-none-any.whl --> alabaster-0.7.13-py3-none-any.whl
• charset_normalizer-2.1.1-py3-none-any.whl --> charset_normalizer-3.0.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
• pytz-2022.7-py2.py3-none-any.whl --> pytz-2022.7.1-py2.py3-none-any.whl
• requests-2.28.1-py3-none-any.whl --> requests-2.28.2-py3-none-any.whl
• zipp-3.11.0-py3-none-any.whl --> zipp-3.12.0-py3-none-any.whl

The sphinx package is 5.3.0 for both cases.

Interestingly, I can reproduce this exact same error locally -- I had some updates to python packages between the 3.4.0 release and now. However I can't really track down what the root cause is, but it's apparently not because of something we did.

I wasn't sure where else to put this, but didn't want to lose track of the details before putting this problem down for a bit.

[andrew-platt]

More details from PR #1442:

Something in RTD changed in January 2023 causing our documentation to fail if doxygen is enabled. This is due to an issue with the paths to doxygen. The change occurred sometime after the 3.4.0 release.

• v3.4.0 (main, e8ec53f) docs build on Jan 11, https://readthedocs.org/projects/openfast/builds/19142412/ --> pass
• v3.4.0 (main, e8ec53f) docs build on Jan 30, https://readthedocs.org/projects/openfast/builds/19322116/ --> fail

Exactly what changed is a bit unknown: looking through the logs for both yielded very little useful information. A handful of python packages had minor updates, but nothing major that we would expect to change the results. Also whatever changed also affects local builds (only for updated python packages).

For this fix, doxygen has been turned off on RTD (we don't think anyone uses it). Doxygen is still built locally and should work on most systems still.

We are leaving this issue open as #1442 is only a temporary stop-gap fix