bug: readthedocs build failing

[hkershaw-brown]

:bug: 🦉

Describe the bug

This bug: https://github.com/readthedocs/readthedocs.org/issues/10290

FIx is to add a .readthedocs.yaml https://docs.readthedocs.io/en/stable/config-file/v2.html

Error Message

e.g. see build https://readthedocs.org/projects/dart-documentation/builds/20552913/ for pull request https://github.com/NCAR/DART/pull/461

[rtd-command-info] start-time: 2023-05-08T14:17:30.846411Z, end-time: 2023-05-08T14:17:31.301907Z, duration: 0, exit-code: 2
python -m sphinx -T -E -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html
Running Sphinx v5.3.0

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/site-packages/sphinx/registry.py", line 459, in load_extension
    mod = import_module(extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/site-packages/sphinx/builders/linkcheck.py", line 18, in <module>
    from requests import Response
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/site-packages/requests/__init__.py", line 43, in <module>
    import urllib3
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/site-packages/urllib3/__init__.py", line 39, in <module>
    "urllib3 v2.0 only supports OpenSSL 1.1.1+, currently "
ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with OpenSSL 1.0.2n  7 Dec 2017. See: https://github.com/urllib3/urllib3/issues/2168

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/site-packages/sphinx/cmd/build.py", line 280, in build_main
    args.pdb)
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/site-packages/sphinx/application.py", line 219, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/site-packages/sphinx/application.py", line 398, in setup_extension
    self.registry.load_extension(self, extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/dart-documentation/envs/461/lib/python3.7/site-packages/sphinx/registry.py", line 463, in load_extension
    err) from err
sphinx.errors.ExtensionError: Could not import extension sphinx.builders.linkcheck (exception: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with OpenSSL 1.0.2n  7 Dec 2017. See: https://github.com/urllib3/urllib3/issues/2168)

Extension error:
Could not import extension sphinx.builders.linkcheck (exception: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with OpenSSL 1.0.2n  7 Dec 2017. See: https://github.com/urllib3/urllib3/issues/2168)

Which model(s) are you working with?

Documentation build on readthedocs

[hkershaw-brown]

still more to fix with this compare: https://docs.dart.ucar.edu/en/latest/README.html with: https://docs.dart.ucar.edu/en/v10.7.0/README.html

search and flyout menu are missing jQuery

[hkershaw-brown]

fix on https://github.com/NCAR/DART/compare/main...doc-search-fix

https://docs.dart.ucar.edu/en/doc-search-fix/README.html

@mjs2369 @johnsonbk question: do we want to pin the python requirements? This fix uses whatever the latest sphinx_rtd_theme with the latest sphinx version.

[mjs2369]

I'm a little confused as to which python requirements we are discussing. Correct me if I'm wrong in this:

We are discussing using either one of two options:

1. to manually declare the Python requirements for our documentation builds by adding the following section to .readthedocs.yaml:

   # Optionally declare the Python requirements required to build your docs
   python:
   install:
   - requirements: docs/requirements.txt

2. use the latest sphinx_rtd_theme , which automatically determines the Python dependencies

[hkershaw-brown]

Yup you got exactly what I getting Marlee. I think use the latest sphinx_rtd_theme is the way to go, and let rtd take care of dependencies.

[hkershaw-brown]

Yup you got exactly what I getting Marlee. I think use the latest sphinx_rtd_theme is the way to go, and let rtd take care of dependencies.

Future Helen to past Helen - you should have pinned the dependencies (Oct 3 2023 readthedocs change).

https://readthedocs.org/projects/dart-documentation/builds/22126149/