Move to readthedocs.yml for configuration

What is the problem?

The instructions in https://github.com/ray-project/ray/blob/master/doc/README.md (or https://docs.ray.io/en/master/development.html#building-the-docs; incidentally, there should probably be a single source of truth there) fail to build the documentation. Ray version and other system information (Python version, TensorFlow version, OS): master Anaconda Python 3.8.5 Ubuntu 18.04

Reproduction (REQUIRED)

Please provide a script that can be run to reproduce the issue. The script should have no external library dependencies (i.e., use fake or mock data / environments):

requirements-rtd.txt has some peculiarities, including version requirements that directly contradict requirements-doc.txt, but whether you use requirements-rtd.txt or not, there are still errors, just different ones.

$ conda create --name raydocenv python=3.8
ray/doc$ ~/anaconda/envs/raydocenv/bin/pip install -r requirements-doc.txt
ray/doc$ ~/anaconda/envs/raydocenv/bin/sphinx-build -b html -d _build/doctrees source _build/html
Running Sphinx v3.0.4

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "raydocenv/lib/python3.8/site-packages/sphinx/config.py", line 319, in eval_config_file
    execfile_(filename, namespace)
  File "raydocenv/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 81, in execfile_
    exec(code, _globals)
  File "/tmp/gitclone/ray/doc/source/conf.py", line 88, in <module>
    sys.modules["tensorflow.keras.callbacks"] = ChildClassMock()
  File "raydocenv/lib/python3.8/site-packages/mock/mock.py", line 2075, in __init__
    self._mock_set_magics()  # make magic work for kwargs in init
  File "raydocenv/lib/python3.8/site-packages/mock/mock.py", line 2085, in _mock_set_magics
    these_magics = orig_magics.intersection(self._mock_methods)
TypeError: 'type' object is not iterable
ray/doc$ ~/anaconda/envs/raydocenv/bin/pip install -U -r requirements-rtd.txt 
ray/doc$ ~/anaconda/envs/raydocenv/bin/sphinx-build -b html -d _build/doctrees source _build/html
Running Sphinx v1.8.5

Extension error:
Could not import extension sphinx_tabs.tabs (exception: cannot import name 'lexer_classes' from 'sphinx.highlighting' (/home/david/anaconda/envs/raydocenv/lib/python3.8/site-packages/sphinx/highlighting.py))

(Incidentally, why even have two different files? Looking at https://readthedocs.org/projects/ray/builds/12372745/, it looks like ReadTheDocs is installing packages as requested, so what would be the point of a requirements-rtd.txt file that sounds like it’s trying to match some existing env somewhere? And what’s in requirements-rtd.txt doesn’t even match what’s configured on ReadTheDocs, anyway. ReadTheDocs is installing different versions: /home/docs/checkouts/readthedocs.org/user_builds/ray/envs/master/bin/python -m pip install --upgrade --no-cache-dir setuptools==41.0.1 mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<2.2. It kind of seems like @sumanthratna had a point. https://github.com/ray-project/ray/issues/10793#issuecomment-693004568)

• I have verified my script runs in a clean environment and reproduces the issue.
• [N/A] I have verified the issue also occurs with the latest wheels.

Relates to https://github.com/ray-project/ray/issues/11687.

[dHannasch]

Incidentally, if we moved towards using a .readthedocs.yml instead of specifying the dependencies (manually, I assume?) through the ReadTheDocs web interface, it would be easier to make pull requests adding documentation dependencies (such as https://github.com/sloria/sphinx-issues to link to extant issues or pull requests).

[stale[bot]]

Hi again! The issue will be closed because there has been no more activity in the 14 days since the last message.

Please feel free to reopen or open a new issue if you’d still like it to be addressed.

Again, you can always ask for help on our discussion forum or Ray’s public slack channel.

Thanks again for opening the issue!